OCPP Error Codes: Complete Reference Guide for Developers

Quick answer: OCPP-J carries errors in a CALLERROR frame: [4, "messageId", "errorCode", "errorDescription", {errorDetails}]. The allowed errorCode values depend on the version. OCPP 1.6 defines 10: NotImplemented, NotSupported, InternalError, ProtocolError, SecurityError, FormationViolation, PropertyConstraintViolation, OccurenceConstraintViolation (the 1.6 spec spells it with one "r"), TypeConstraintViolation, and GenericError. OCPP 2.0.1 and 2.1 define 12: FormationViolation becomes FormatViolation, the occurrence code is spelled OccurrenceConstraintViolation, and two codes are new: MessageTypeNotSupported and RpcFrameworkError. The strings are case-sensitive, so a peer that validates them strictly rejects a code from the other version.

OCPP error codes are the standardized error responses defined by the Open Charge Point Protocol for communicating failures between charge points and the CSMS (Charging Station Management System) (OCPP 1.6: Central System). Understanding these errors is essential for every developer building, integrating, or debugging EV charging infrastructure.

When an OCPP message cannot be processed, the receiving party responds with a CALLERROR message containing a specific error code, a human-readable description, and optional error details. Misinterpreting these errors or failing to handle them correctly leads to stuck transactions, offline chargers, and frustrated drivers. The full error-code enum is normative in the OCPP-J transport profile published by the Open Charge Alliance. The OCPP 1.6 JSON specification defines 10 error codes. OCPP 2.0.1 Part 4 (and OCPP 2.1, which keeps the same list) defines 12: it renames two codes and adds two. The payload schemas differ between versions too, as our OCPP 1.6 vs 2.0.1 comparison explains.

This guide covers every OCPP error code, their common causes, and how to resolve them.

How Does OCPP Error Handling Work?

OCPP uses a simple request-response model over WebSocket. Every request (CALL) receives either a success response (CALLRESULT) or an error response (CALLERROR). There is no concept of partial success or warnings within the protocol itself. For a breakdown of the three frame types, see our OCPP message types reference.

The CALLERROR Message Format

A CALLERROR is a JSON array with message type 4:

[4, "messageId", "errorCode", "errorDescription", {errorDetails}]

Per the OCPP-J transport profile defined in the OCPP 1.6 specification, the errorDescription field is capped at 255 characters, while the errorDetails object structure is implementation-defined.

Example CALLERROR Exchange

A charger sends an Authorize request:

[2, "auth-001", "Authorize", {
  "idTag": "RFID-XYZ789"
}]

The CPMS encounters an internal database failure and responds:

[4, "auth-001", "InternalError",
  "Authorization service temporarily unavailable",
  {"retryAfter": 30}]

The messageId ("auth-001") matches the original request, identifying which CALL this error corresponds to. The errorDetails object can contain any additional information the sender deems useful, though its structure is not standardized.

What Are All the OCPP Error Codes?

Send the code that matches the OCPP version negotiated in the WebSocket subprotocol (ocpp1.6, ocpp2.0.1 or ocpp2.1):

NotImplemented

Description: The requested action is not known by the receiver.

Common Causes:

• Sending an OCPP 2.0.1 action to a CPMS that only supports OCPP 1.6
• Typo in the action name (e.g., "BootNotification" vs "bootNotification" — OCPP is case-sensitive)
• Custom or proprietary actions that the other party does not recognize
• Protocol version mismatch between charger and CPMS

How to Fix:

• Verify the action name matches the OCPP specification exactly, including casing
• Confirm both parties are using the same OCPP version
• Check the WebSocket subprotocol negotiation to ensure version agreement
• Review the CPMS or charger documentation for supported action lists

[4, "msg-001", "NotImplemented",
  "Action 'DataTransfer' is not implemented",
  {}]

NotSupported

Description: The action is recognized but intentionally not supported by the receiver.

Common Causes:

• Sending SetChargingProfile to a charger that does not support smart charging
• Requesting GetDiagnostics from a charger without diagnostics capability
• Using optional OCPP features that the implementation chose not to include
• Feature profile not enabled on the charger firmware

How to Fix:

• Check the charger's supported feature profiles in its documentation or configuration
• In OCPP 2.0.1, verify the device model's supported feature list
• Implement fallback logic for optional features that may not be universally supported
• Do not confuse with NotImplemented — NotSupported means the receiver knows the action but explicitly declines it

[4, "msg-002", "NotSupported",
  "SetChargingProfile is not supported by this charge point",
  {"supportedProfiles": ["Core", "FirmwareManagement"]}]

InternalError

Description: An internal error occurred in the receiver that prevented processing the request.

Common Causes:

• Database connection failure on the CPMS
• Out-of-memory condition on the charge point
• Unhandled exception in the message processing logic
• Downstream service unavailable (payment gateway, authorization service)
• File system full on the charge point (preventing log or cache writes)

How to Fix:

• Check server/charger logs for the underlying exception or error
• Monitor system resources (CPU, memory, disk, database connections)
• Implement retry logic with exponential backoff on the calling side
• Ensure all downstream dependencies have health checks and circuit breakers
• This is a catch-all for server-side failures, so root cause analysis requires log inspection

[4, "msg-003", "InternalError",
  "Database connection pool exhausted",
  {"timestamp": "2025-02-08T14:30:00Z"}]

ProtocolError

Description: In OCPP 1.6 the spec defines it as "Payload for Action is incomplete". In OCPP 2.0.1 and 2.1 it means the payload does not conform to the PDU structure for the action; a payload that is not even valid JSON is a FormatViolation instead.

Common Causes:

• Sending a CALLRESULT with the wrong payload structure for the action
• Message ID format violations
• Sending a response to a message ID that was never sent
• Incorrect message type identifier (e.g., using 2 instead of 3 for a response)
• Violating the OCPP requirement that only one CALL can be pending per direction

How to Fix:

• Validate all messages against the OCPP JSON schema before sending
• Ensure message IDs are correctly tracked and matched between CALL and CALLRESULT/CALLERROR
• Verify that your implementation does not send a new CALL before receiving the response to the previous one
• Use a protocol-level message validator in your development environment

[4, "msg-004", "ProtocolError",
  "Received CALLRESULT for unknown messageId",
  {"receivedMessageId": "unknown-123"}]

SecurityError

Description: A security-related issue prevented processing the request.

Common Causes:

• Invalid or expired TLS client certificate
• HTTP Basic Auth credentials rejected
• Charge point identity does not match the certificate's Common Name
• Attempting to perform an action that requires higher security profile authorization
• Tampered message detected (in implementations using message signing)

How to Fix:

• Verify TLS certificate validity, chain completeness, and expiration dates
• Confirm HTTP Basic Auth credentials match the CPMS configuration
• Ensure the charge point's identity string matches across all security layers
• Check that the security profile configured on the charger matches the CPMS expectations
• Review certificate provisioning and rotation processes

[4, "msg-005", "SecurityError",
  "Client certificate CN does not match charge point identity",
  {"expected": "CP001", "received": "CP002"}]

FormationViolation (1.6) / FormatViolation (2.0.1, 2.1)

Description: The payload is syntactically incorrect. OCPP 1.6 calls this FormationViolation and also uses it when the payload does not conform to the PDU structure. OCPP 2.0.1 and 2.1 rename it to FormatViolation and limit it to syntax errors; PDU structure errors go to ProtocolError.

Common Causes:

• Malformed JSON (missing brackets, trailing commas, unescaped characters)
• Sending a string where the protocol expects a JSON array
• Incorrect encoding (the payload must be UTF-8)
• Truncated messages due to WebSocket framing issues
• Buffer overflow causing partial message transmission

How to Fix:

• Validate JSON syntax before sending any OCPP message
• Ensure your WebSocket library correctly handles message framing and does not split messages
• Use a JSON linter in your CI/CD pipeline to catch formation errors in test payloads
• Check character encoding settings on both sides

OCPP 1.6:

[4, "msg-006", "FormationViolation",
  "Payload is not valid JSON",
  {"receivedPayload": "{malformed..."}]

OCPP 2.0.1 and 2.1:

[4, "msg-006", "FormatViolation",
  "Payload is not valid JSON",
  {"receivedPayload": "{malformed..."}]

PropertyConstraintViolation

Description: A property value in the payload violates a defined constraint (e.g., string length, numeric range, enum value).

Common Causes:

• idTag exceeding the 20-character maximum length defined in the OCPP 1.6 specification
• Negative value for meterValue or transactionId
• Enum value not in the allowed set (e.g., sending "Active" instead of "Charging" for ChargePointStatus)
• Timestamp not in ISO 8601 format
• String value exceeding maxLength defined in the OCPP JSON schema

How to Fix:

• Validate all property values against the OCPP JSON schema constraints before sending
• Pay particular attention to string length limits, which vary by field
• Use the exact enum values specified in the OCPP specification (case-sensitive)
• Ensure numeric values fall within the defined ranges

[4, "msg-007", "PropertyConstraintViolation",
  "idTag exceeds maximum length of 20 characters",
  {"property": "idTag", "maxLength": 20, "actualLength": 25}]

OccurenceConstraintViolation (1.6) / OccurrenceConstraintViolation (2.0.1, 2.1)

Description: A required property is missing from the payload, or a property that should appear only once appears multiple times. The OCPP 1.6 spec spells the code OccurenceConstraintViolation (one "r"); OCPP 2.0.1 and 2.1 spell it OccurrenceConstraintViolation. Send the spelling of the negotiated version, and accept both when you receive if you talk to older 1.6 firmware.

Common Causes:

• Omitting required fields like chargePointVendor in BootNotification
• Missing connectorId in StatusNotification
• Omitting idTag in StartTransaction
• Required nested objects not included (e.g., missing chargingSchedule in a ChargingProfile)

How to Fix:

• Cross-reference your message payloads against the OCPP specification for required vs optional fields
• Implement schema validation that checks required field presence before sending
• Be aware that required fields differ between OCPP 1.6 and 2.0.1 for the same action
• Check for conditional requirements (fields that are required only when another field has a specific value)

[4, "msg-008", "OccurenceConstraintViolation",
  "Required property 'chargePointVendor' is missing",
  {"action": "BootNotification", "missingProperty": "chargePointVendor"}]

TypeConstraintViolation

Description: A property has the wrong data type (e.g., a string where an integer is expected).

Common Causes:

• Sending connectorId as a string "1" instead of integer 1
• Sending meterValue as a string instead of a number
• Boolean values sent as strings ("true" instead of true)
• Sending an integer where the schema expects a decimal number
• Date/time values not formatted as strings

How to Fix:

• Ensure JSON serialization preserves correct types (a common issue in dynamically typed languages)
• Validate payloads against the JSON schema with strict type checking
• Be especially careful with languages that auto-convert between strings and numbers
• Test with a schema validator that catches type mismatches

[4, "msg-009", "TypeConstraintViolation",
  "Property 'connectorId' must be integer, received string",
  {"property": "connectorId", "expectedType": "integer", "receivedType": "string"}]

GenericError

Description: A catch-all error code for any error that does not fit the other categories.

Common Causes:

• Timeout waiting for a downstream system response
• Rate limiting or throttling
• Temporary resource contention
• Implementation-specific errors that have no matching standard code
• Edge cases not covered by the OCPP specification

How to Fix:

• Read the errorDescription carefully — it is the primary source of information for GenericError
• Check the errorDetails object for implementation-specific context
• Contact the CPMS or charger vendor if the error description is unclear
• Implement retry logic, as GenericError often indicates transient conditions

[4, "msg-010", "GenericError",
  "Request timed out waiting for authorization service",
  {"timeoutMs": 5000}]

MessageTypeNotSupported (2.0.1, 2.1 only)

Description: The receiver got a message with a MessageTypeId it does not support. OCPP 2.0.1 Part 4 requires this response when an implementation receives an unknown message type; the sender then closes the connection or falls back to CALL, CALLRESULT and CALLERROR.

Common Causes:

• A peer sending an extension message type (anything other than 2, 3 or 4) to a 2.0.1 implementation
• A bug that writes the wrong number in the first array element

[4, "msg-011", "MessageTypeNotSupported",
  "MessageTypeId 7 is not supported",
  {}]

RpcFrameworkError (2.0.1, 2.1 only)

Description: The content of the message is not a valid RPC request, for example the MessageId cannot be read. Use it when the frame itself is broken, before the action payload can be validated.

Common Causes:

• A CALL array with missing elements
• A MessageId that is not a string

[4, "msg-012", "RpcFrameworkError",
  "MessageId could not be read",
  {}]

Error Code Summary Table

How Do You Troubleshoot Common OCPP Errors?

Charger Will Not Connect

Symptoms: WebSocket connection fails or immediately closes after handshake.

Diagnostic Steps:

1. Verify the CPMS WebSocket URL is correct, including the charge point identity in the path
2. Check that the OCPP subprotocol header is present and matches a version the CPMS supports
3. Confirm TLS certificates are valid if using WSS (check expiration, chain, and CN)
4. Ensure the CPMS is configured to accept the charge point's identity
5. Check firewall rules and load balancer configuration for WebSocket support
6. Verify that no other charge point is connected with the same identity

Authorization Fails

Symptoms: Authorize requests return Invalid or Blocked status, or trigger CALLERROR.

Diagnostic Steps:

1. Verify the idTag is registered in the CPMS and is in Accepted status
2. Check idTag format and length (max 20 characters in OCPP 1.6)
3. Confirm the authorization cache (Local Auth List) is synchronized between charger and CPMS
4. Check if the parent idTag group is blocked or expired
5. Verify the authorization service is responsive (InternalError in the response indicates a backend failure)

Transactions Stuck in Started State

Symptoms: Transactions never receive a StopTransaction and remain open indefinitely.

Diagnostic Steps:

1. Check if the charger disconnected during a transaction (WebSocket connection dropped)
2. Verify the charger is sending StopTransaction when the cable is unplugged or session times out
3. Look for InternalError responses to StopTransaction that may prevent the CPMS from processing the stop
4. Check for transactionId mismatches between StartTransaction response and subsequent StopTransaction
5. Implement transaction timeout logic on the CPMS side as a safety net

Meter Values Missing or Incorrect

Symptoms: Charging sessions show zero energy, or meter values have gaps or unrealistic values.

Diagnostic Steps:

1. Verify MeterValues clock-aligned interval is configured on the charger
2. Check that the CPMS is correctly parsing the sampledValue array and its nested structure
3. Confirm measurand values match what you expect (Energy.Active.Import.Register for cumulative energy)
4. Check for timezone issues — meter value timestamps should be in UTC
5. Verify that MeterValues messages are not being dropped due to WebSocket disconnections

How Do You Debug OCPP Errors?

WebSocket Inspection

Use browser developer tools, wscat, or dedicated WebSocket clients to monitor raw OCPP messages. Capture the full message exchange including WebSocket handshake headers, subprotocol negotiation, and all CALL/CALLRESULT/CALLERROR frames.

Message Logging

Implement structured logging for every OCPP message with:

• Timestamp (millisecond precision)
• Direction (charger-to-CPMS or CPMS-to-charger)
• Message type (CALL, CALLRESULT, CALLERROR)
• Message ID
• Action name
• Full payload (redact sensitive fields like passwords)
• Processing duration

Timeout Analysis

OCPP does not define a standard timeout for CALL responses, so the value is left to each implementation. Track response times for every message type to identify:

• Slow actions that may indicate backend performance issues
• Timeouts that cause the sender to assume failure and retry
• Cascading timeouts from downstream service dependencies

How Does OCPPLab Help Debug OCPP Errors?

Reproducing OCPP errors with physical chargers is slow and limited. You cannot easily force a charger to send malformed JSON, trigger specific error codes, or reproduce timing-sensitive race conditions — which is why a dedicated OCPP testing workflow matters.

OCPPLab provides complete control over OCPP message flows for systematic error debugging:

• Full Message Inspection: View every OCPP message with timestamps, raw JSON payloads, and decoded field values. Identify exactly where in a message exchange an error occurs.
• Error Injection: Send specific CALLERROR responses to test how your CPMS handles each error code. Verify retry logic, fallback behavior, and error reporting.
• Malformed Message Testing: Send messages with missing fields, wrong types, invalid JSON, or constraint violations to validate your CPMS error handling covers all edge cases.
• Scenario Replay: Capture a problematic message sequence from production logs and replay it through OCPPLab to reproduce and diagnose the issue in a controlled environment.
• Concurrent Error Simulation: Test how your CPMS behaves when multiple chargers simultaneously encounter errors, revealing race conditions and resource exhaustion issues.

Frequently Asked Questions

Are OCPP error codes the same in 1.6 and 2.0.1?

No. OCPP 1.6 defines 10 codes and OCPP 2.0.1 defines 12 (OCPP 2.1 keeps the 2.0.1 list). 2.0.1 renames FormationViolation to FormatViolation, corrects the 1.6 spelling OccurenceConstraintViolation to OccurrenceConstraintViolation, and adds MessageTypeNotSupported and RpcFrameworkError. The CALLERROR frame format is the same in both versions.

Should my CPMS retry after receiving a CALLERROR?

It depends on the error code. InternalError and GenericError are often transient and worth retrying with exponential backoff. NotImplemented, NotSupported, FormationViolation / FormatViolation, and constraint violations indicate permanent problems that retrying will not resolve. Always check the errorDescription for hints about whether the condition is temporary.

How do I handle errors in production?

Implement a layered approach: log every CALLERROR with full context, alert on elevated error rates, and build dashboards that track error codes by charger model and firmware version. Many production issues are firmware-specific, so correlating errors with charger metadata helps identify the root cause quickly.

What happens if neither side sends a response?

If a CALL receives no CALLRESULT or CALLERROR within the timeout period, the sender should consider the request failed. The OCPP specification does not define a specific timeout value, so it is left to each implementation. After a timeout, the sender may retry the request or close the connection and reconnect.

Can I define custom error codes?

No. The OCPP specification defines a fixed set of error codes, and both parties must use only these. If you need to communicate additional error context, use the errorDescription string and the errorDetails JSON object, which can contain any structured data you need.