Troubleshoot Platform Connect / UAMS Registration TLS Handshake Failures

Symptoms

• Platform Connect shows failed status for registration/connectivity

• Agent does not appear in SolarWinds Observability SaaS after install

• Repeated registration retry messages in UAMS logs

• Errors such as:

  • authentication handshake failed

  • connection forcibly closed by remote host

  • missing selected ALPN property

UAMS uses secure gRPC communication, which requires HTTP/2 negotiation (ALPN h2).
If a proxy, firewall, or TLS inspection device intercepts/decrypts traffic and alters handshake negotiation, registration can fail.

Step 1: Identify your region and endpoints

Check your SolarWinds Observability SaaS region and refer to the official endpoint documentation:
SolarWinds Observability | Data centers and endpoint URIs

Common regions include:

• na-01 (North America)

• eu-01 (Europe)

• ap-01 (Asia-Pacific)

Endpoints differ by region. Use the doc above to find your specific endpoints.

Step 2: Confirm required endpoints and connectivity

Run connectivity checks from the affected server to the required endpoints (TCP 443).

Example for na-01 region (most common):

Full TLS/HTTP attempt with verbose output

If using proxy, identify the egress path - direct vs proxy

For other regions:

Replace na-01 with your region (e.g., eu-01, ap-01) in the UAMS and OTEL collector endpoints.

All Test-NetConnection commands should report TcpTestSucceeded: True. If any fail, check firewall/network policy first.

Note for SolarWinds Platform server: agent-binaries.cloud.solarwinds.com must be reachable on port 443 from the Orion server for Platform Connect to download and install uamsclient.msi automatically. If this endpoint is blocked, automatic agent installation will fail and manual download/install is required.

Step 3: Run the TLS diagnostic tool

Run the built-in diagnostic tool from the affected server. uamsclient-ctl.exe is installed as part of the UAMS Client (uamsclient.msi). If the UAMS Client is not yet installed or was removed, install it first — see the links below.

The tool tests all required SolarWinds endpoints automatically and writes full output to diag.log in the current folder. Share that file with SolarWinds Support.

UAMS Client installation reference:

• Add new SolarWinds Observability Agents — step-by-step guide including MSI download and install command

What a healthy result looks like

At the end of diag.log you should see the summary with all endpoints passing and no MITM detected:

If you see failed=1 or higher, or mitm_detected=true on any endpoint, proceed to the Resolution section below.

Step 4: Proxy server setup

If the affected server accesses the internet through a proxy server, the UAMS Client must be configured to use it. Without proper proxy configuration, the agent cannot reach SolarWinds endpoints even if the proxy itself allows the traffic.

Configure the proxy for UAMS Client

Run the following command on the affected server:

Replace <ProxyServerIPAddress> with the IP address (and port if applicable) of your proxy server — for example:

Verify and re-run diagnostics

After setting the proxy, re-run the diagnostic from Step 3 to confirm the agent can now reach all required endpoints through the proxy:

All endpoints should show status=SUCCESS. If any still fail, verify that the proxy allows outbound HTTPS (port 443) traffic to all SolarWinds endpoints listed in Step 1.

Common proxy considerations

• If your proxy performs TLS inspection, the SolarWinds endpoints must still be added to a no-decrypt / bypass list — see the Resolution section.

• System-level proxy settings (e.g., netsh winhttp) are not automatically inherited by the UAMS Client. You must configure the proxy explicitly using uamsclient-ctl set-proxy as shown above.

• On Linux, use the same uamsclient-ctl binary located in /opt/solarwinds/uamsclient/.

Resolution

If mitm_detected: true or certificate/connection errors are reported, work with your network/security team to:

1. Identify the SSL inspection / proxy device on the outbound path (e.g., Zscaler, Netskope, Palo Alto, FortiGate)

2. Add a TLS inspection bypass (no-decrypt exception) for:

   • Your UAMS endpoint — e.g., uams.na-01.cloud.solarwinds.com

   • Your OTel Collector endpoint — e.g., otel.collector.na-01.cloud.solarwinds.com

   • agent-plugins.cloud.solarwinds.com

   • Full endpoint list: Data centers and endpoint URIs

3. Apply the policy and allow it to propagate

Validate the fix

Once the bypass is in place:

1. Re-run the diagnostic:

Expected: relevant endpoints show status: SUCCESS and mitm_detected: false

2. Retry agent registration in Platform Connect

3. Confirm the agent appears in SolarWinds Observability SaaS and stays connected