OCPP Connection Not Working? How to Diagnose WebSocket and Handshake Errors

A connection to a CSMS can fail in five places: the name lookup, the TCP and TLS connection, the HTTP upgrade to WebSocket, the OCPP subprotocol, and the first OCPP message. From the outside they all look like a station that does not connect. The fastest way to tell them apart is to run a single real handshake and see how far it gets.

Run the probe first

curl -X POST https://api.simitnow.com/v1/cs/probe   -H "SIMITNOW-API-KEY: $API_KEY"   -H "Content-Type: application/json"   -d '{"csmsUrl":"wss://csms.example.com/ocpp","id":"CP-001","protocol":"ocpp1.6"}'

{"ok": false, "code": "credentials_refused",
 "cause": "The server refused these credentials",
 "action": "Is this station registered in your CSMS? Does it require Basic auth?",
 "stages": {"dns": "ok", "tcp_tls": "ok", "ocpp_ws": "fail"},
 "statusCode": 401, "url": "wss://csms.example.com/ocpp/CP-001"}

The probe opens one real WebSocket handshake and closes it. It creates nothing and sends no BootNotification, so no OCPP session starts, although your CSMS still sees one connection attempt. A failed handshake still returns HTTP 200, and the verdict is in the body. The handshake times out after 8 seconds, and you can run 20 probes a minute per API key. Use the real charge point id, since many CSMSs route or authenticate on it. Pass the same security object the station will use, because a probe without it connects unauthenticated and a correctly configured station then shows up as credentials_refused.

Reading the diagnosis code

The stages field shows how far the attempt got: dns, tcp_tls and ocpp_ws, each ok, fail or skipped. The code tells you why.

Before a connection exists:

• dns_failure: the domain did not resolve. Check the spelling.
• address_not_reachable: the name points at a private or loopback address that SimItNow's servers cannot reach. Use a public address or expose your CSMS through a tunnel, as described in testing a local CSMS with ngrok or Cloudflare Tunnel.
• connection_refused: the port is closed.
• no_response: nothing answered before the timeout. The server is down, or a firewall drops the connection.

During TLS:

• certificate_untrusted: the certificate could not be verified. Fix the chain, or set skipServerCertVerify for a test setup.
• tls_failed: the handshake was rejected. The port may not speak TLS, so try ws:// or another port.

During the HTTP upgrade:

• credentials_refused: the server answered 401 or 403. Check that the station is registered and whether it needs Basic Auth.
• path_not_found: the server answered 404. The path is wrong, or the station id is not known.
• csms_busy: the server answered 429 or 503. This is temporary.
• not_websocket: any other answer to the upgrade request. It can be an ordinary web page, but also a 400 (a subprotocol or header problem is a common cause) or a 500. Read statusCode.

At the subprotocol and in the input:

• protocol_not_supported: the handshake completed but the server did not agree to the OCPP version you asked for. Try another version.
• invalid_url and invalid_security_profile: the request itself is malformed, for example a bad port, a missing password, or a certificate and key that do not load. Nothing was dialled.

The handshake works but the station will not stay connected

The probe can report ok and the station can still fail. Two causes are common.

The first is the chargebox id in the URL twice. SimItNow appends the station id as the last path segment, so csmsUrl must stop before it:

Wrong: csmsUrl "wss://your-csms/ocpp/CP-001" + id "CP-001"  ->  wss://your-csms/ocpp/CP-001/CP-001
Right: csmsUrl "wss://your-csms/ocpp"        + id "CP-001"  ->  wss://your-csms/ocpp/CP-001

Many CSMS gateways route generically, so the upgrade and the subprotocol succeed against the doubled path. The failure appears only after the BootNotification, when the CSMS cannot map the path to a station and closes with code 1002. The station then reconnects and repeats it. The probe cannot see this, but its response includes the exact url it dialled, so read that field.

The second is the OCPP version. A SimItNow station offers exactly one version, the one you created it with. If your CSMS speaks only another, the station cannot negotiate a subprotocol. Probe each version before you create the station and use the one that comes back ok. Against the hosted CSMS, a charger that offers no supported subprotocol is closed with 1002 and the reason is written to the Activity Log.

Read the Activity Log

The Activity Log on the dashboard shows the OCPP frames of your stations. Look for the BootNotification call and what follows it. A CallResult with status Accepted means the CSMS took the station. A CallError carries an error code and a description. Nothing at all means the CSMS is not answering.

How the station retries

A station never gives up. A CSMS that keeps rejecting it, because it is busy, refuses the credentials or does not know the URL, makes the wait grow geometrically up to about a minute (30 to 60 seconds with jitter). Once you fix the CSMS or the configuration, the station reconnects on its own, and after a long run of refusals that takes up to a minute.

Create a free account to probe your own CSMS.