Charger will not connect
Diagnose OCPP WebSocket failures when a charge point never boots, drops immediately, or never sends BootNotification to GridOS.
Use this guide when a station is offline in the Dashboard or never completes the OCPP connect path. For the healthy setup checklist, see Connect a charger.
Confirm the basics
- Charge point identity — the device id must match the Dashboard charger record exactly (treat matching as case-sensitive).
- CSMS URL — protocol
ws/wss, host, path, and port match the GridOS endpoint for your environment. - Outbound network — the site firewall allows outbound WebSocket (TLS on 443 is typical).
- Protocol version — device is configured for the OCPP version Dashboard expects (1.6 JSON or 2.0.1).
Common failure modes
| Observation | Likely cause | What to try |
|---|---|---|
| No TCP/TLS to CSMS | Wrong host, DNS, or blocked egress | Ping/curl from a host on the same LAN path; fix URL or firewall |
| TLS handshake error | Missing/invalid CA, wrong SNI, or outdated TLS | Prefer wss; update device trust store; confirm endpoint cert chain |
| Connect then immediate close | Auth profile mismatch (basic auth, client cert) | Align security profile with Dashboard; rotate credentials |
| Connected but no BootNotification | Wrong OCPP version or stuck firmware state | Reboot after config change; confirm JSON OCPP; check device logs |
| BootNotification Rejected / Pending forever | Unknown identity or registration policy | Re-check charge point id in Dashboard; accept pending registration if your org uses that flow |
| Online then flapping | Heartbeat interval, NAT timeout, or unstable link | Lower interval only if runbook allows; stabilize network; review Heartbeat / StatusNotification pages |
Message-level detail
- BootNotification (1.6)
- Heartbeat (1.6)
- StatusNotification (1.6)
- OCPP 2.0.1: start from OCPP 2.0.1 Actions and search for Boot / Heartbeat / Status
Simulate before field work
Reproduce with Simulating a charger against the same org endpoint. If the simulator boots and the field unit does not, focus on device config and site network rather than CSMS availability.
Still stuck
- Capture Dashboard last error / connection timestamp.
- Capture device log around reconnect (BootNotification payload if any).
- Open a docs or support issue with charge point id (redact secrets), OCPP version, and exact CSMS URL host (not credentials).