Agent Client Collector – TLS handshake failure and API key authentication error - Support and Troubleshooting

Agent Client Collector – TLS handshake failure and API key authentication error Issue .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } After installing the Agent Client Collector (ACC), the agent cannot establish a secure WebSocket connection to the MID Server. The following error appears repeatedly in acc.log:

[ERROR] [agent] [tls: first record does not look like a TLS handshake] reconnection attempt failed to the url: wss:// :8800/ws/events, using api-key authentication failed Additional symptoms observed in acc.log: -

Agent successfully started appears, but is followed by HTTP 401 or 404 responses, I/O errors, and repeated reconnection attempt failed to the URL messages.

This behaviour is caused by one or more of the following configuration issues:

Incorrect backend URL or WebSocket endpoint — The `backend_url` in acc.yml does not match the WebSocket Endpoint configured in the ServiceNow instance. An incorrect hostname, IP address, port, or path (for example, `/ws/events`) causes TLS handshake failures and 404 errors.

Invalid or outdated API key — The API key configured in acc.yml is incorrect, expired, or does not match the one generated in the ServiceNow instance. This causes 401 Unauthorized errors and the `using api-key authentication failed` message.

Connectivity or TLS negotiation problem — Even when the URL and API key are correct, network or TLS issues on the specified IP address and port can cause the `first record does not look like a TLS handshake` error.

Symptoms .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } After installing the Agent Client Collector (ACC), the agent fails to connect to the MID Server WebSocket endpoint. The acc.log shows a TLS handshake error and an API key authentication failure. This article explains the causes and provides steps to resolve the issue.

Release .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } ALL

Cause .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } This behavior is typically caused by one or more of the following configuration issues:

Incorrect backend URL / WebSocket endpoint The backend_url in acc.yml does not match the WebSocket Endpoint configured in the ServiceNow instance. A wrong hostname/IP, port, or path (e.g., /ws/events ) leads to TLS handshake failures and 404 errors. Invalid or outdated API key The API key configured in acc.yml is incorrect, expired, or does not match the one generated in the ServiceNow instance. This results in 401 Unauthorized errors and "using api-key authentication failed". Connectivity / TLS negotiation problem Even if the URL and API key are correct, network or TLS issues on the specified IP/port can cause the "first record does not look like a TLS handshake" error. Resolution .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Follow the following steps to validate and correct the configuration.

1. Confirm the backend URL format

Ensure the ACC backend URL strictly follows this format:

wss:// : /ws/events In the ServiceNow instance, go to Agent Client Collector > Deployment > WebSocket Endpoint. Open the relevant WebSocket Endpoint record and copy the WebSocket Endpoint value.

On the ACC host, open the acc.yml configuration file. Update the `backend_url` entry so it matches the WebSocket Endpoint exactly (replacing the IP address or hostname only if needed), for example:

backend_url: "wss:// :8800/ws/events" Save the file.

2. Update and validate the API key

In the ServiceNow instance, generate or retrieve the ACC API key that this agent should use. On the ACC host, open acc.yml and locate the API key section:

auth: type: api-key api_key: " " Update api_key with the new value. Save the file.

3. Verify the WebSocket and MID web server with curl

From the ACC host, or from a machine that can reach the MID Server host and port, run the following command:

curl -Lk -H "Authorization: Key " https:// : /api/mid/mon Replace with the same key used in acc.yml. Replace and with the MID Server address and web server port.

Expected result: A valid JSON response from the MID web server.

If TLS errors, connection timeouts, or 401 or 404 responses are returned, verify the following:

Network connectivity and firewall rules to the MID Server port. That the API key is correct and active. - That the MID web server is running and listening on the specified port. 4. Review logs and confirm resolution

Restart the ACC service after making changes.

Monitor acc.log and confirm the following:

Agent successfully started appears. The errors tls: first record does not look like a TLS handshake , using api-key authentication failed , and any 401, 404, or I/O errors no longer appear. ACC is shown as connected in the ServiceNow instance. - Data collection jobs are running successfully. Related Links .ns-kb-css-body-editor-container { p { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } span { font-size: 12pt; font-family: Lato; color: var(--now-color--text-primary, #000000); } h2 { font-size: 24pt; font-family: Lato; color: var(--now-color--text-primary, black); } h3 { font-size: 18pt; font-family: Lato; color: var(--now-color--text-primary, black); } h4 { font-size: 14pt; font-family: Lato; color: var(--now-color--text-primary, black); } a { font-size: 12pt; font-family: Lato; color: var(--now-color--link-primary, #00718F); } a:hover { font-size: 12pt; color: var(--now-color--link-primary, #024F69); } a:target { font-size: 12pt; color: var(--now-color--link-primary, #032D42); } a:visited { font-size: 12pt; color: var(--now-color--link-primary, #00718f); } ul { font-size: 12pt; font-family: Lato; } li { font-size: 12pt; font-family: Lato; } img { display: ; max-width: ; width: ; height: ; } } Please refer to KB1638987 - How to check ACC i/o timeout error issues