Server-initiated agent fails to connect when a passive SolarWinds Platform Agent Shared Secret contains special characters (", ', \)

A server-initiated (passive) agent listens on its passive port (default 17790) and waits for the SolarWinds Platform server to initiate the connection. The Agent Shared Secret is used only for the initial trust/authentication handshake between the polling engine and the agent; after that handshake succeeds, ongoing communication is secured by certificates rather than the secret itself.

When the shared secret contains one or more unsupported special characters, the initial authentication handshake fails. Because the handshake never completes, the console cannot establish the session and surfaces a generic connection failure — so the underlying cause (an unsupported character in the secret) is not obvious from the message alone.

The issue is reproducible with the following behavior:

• Windows agent: a double quote (") in the shared secret breaks the initial connection.
• Linux/Unix agent (including IBM AIX): the characters double quote ("), single quote ('), and backslash (\) in the shared secret cause the failure.

Symptoms

• In the Web Console (Settings > All Settings > Manage Agents > Add Agent > Connect to a previously installed agent), submitting a server-initiated agent that uses a shared secret containing an affected character fails.
• The agent shows as not connected / Unknown in Manage Agents, or the add/connect action returns a connection error.
• The agent process is running on the host and the passive port (17790) is reachable, yet the connection still fails.
• Removing a working agent and re-adding it with the same complex secret reproduces the failure.

The figure below shows a generic representation of the Add Agent dialog where a server-initiated agent with a shared secret fails with a "Connection refused" message.

Figure 1: Add Agent page with Server initiated communication selected. When the agent uses a shared secret that contains an unsupported special character, the connection fails with "Attempt to connect to the agent at 10.0.0.100:17790 was unsuccessful. Additional details: Connection refused."

The initial authentication handshake for a server-initiated (passive) agent does not correctly handle certain special characters in the Agent Shared Secret. When the secret includes an affected character, the secret is not interpreted as expected during the handshake, so authentication fails and the connection is refused.

Affected characters observed:

• Windows agent: double quote (").
• Linux/Unix agent (including IBM AIX): double quote ("), single quote ('), and backslash (\).

Note: The secret can look identical on the agent and in the console, so a visual comparison does not reveal the problem. Other conditions — a blocked passive port (17790) or an incompatible internal SolarWinds-Orion certificate — can produce the same "Connection refused" message, so rule those out (see Resolution) before concluding this is the shared-secret issue.

Use a shared secret that contains only supported characters, and apply the same value on both the agent and the Web Console.

1. Choose a new Agent Shared Secret that uses letters and numbers only. Avoid ", ', and \, and avoid complex punctuation sequences.
• A reasonably strong alphanumeric value (letters and numbers) is recommended.
2. Update the shared secret on the agent host:
• Windows: Log in to the host with an administrator account. Open Orion Agent Settings in the Control Panel. Select SolarWinds Platform server Initiated Communication, set the new Agent Shared Secret, and click OK.
• Linux: Log in to the host, open a terminal, and run as root: service swiagentd init. Configure server-initiated communication and set the new shared secret, then save.
• IBM AIX / Unix: Log in to the host, open a terminal, and run as root: /opt/SolarWinds/Agent/bin/swiagentaid.sh init. Configure server-initiated communication and set the new shared secret, then save (enter the save option to apply).
3. In the SolarWinds Platform Web Console, connect/register the agent with the matching secret:
• Click Settings > All Settings, and under Node & Group Management click Manage Agents.
• Click Add Agent > Connect to a previously installed agent > Next.
• Enter the agent name and the host IP address or hostname (for example, hostname01.example.com).
• Select Server-initiated communication.
• Enter the same Agent Shared Secret you set on the host.
• Click Submit / Add Agent.
4. Confirm the result: when the handshake succeeds, the agent appears on the Manage Agents page with a Connected/OK status.

If the connection still fails after switching to an alphanumeric secret, collect agent and polling engine diagnostics and verify the network path (passive port 17790 reachable) and the internal SolarWinds-Orion certificate (2048-bit RSA recommended) before concluding this is the shared-secret issue.

Note on a permanent fix: As of July 6, 2026, the fix implementation date has not yet been defined. Monitor this KB or the product release notes for product fixes and enhancements.