DeserializationError

Description

Tells why deserializeJson() or deserializeMsgPack() failed.

Values

A DeserializationError is an enumerated type that can contain one of the following values:

DeserializationError::Ok

The deserialization succeeded. Cool!

DeserializationError::EmptyInput

The input was empty or contained only spaces or comments. Possible reasons:

• a timeout occurred when reading from a stream (see How to change the timeout)
• the server returned a redirection code (like 301 Moved Permanently or 302 Found)
• the certificate validation failed (try WiFiClientSecure::setInsecure())
• the stream is not connected
• the file was not found
• the file is empty
• the file was opened in the wrong mode

EmptyInput was added in ArduinoJson 6.17.0

DeserializationError::IncompleteInput

The end of the input is missing. Possible reasons:

• a buffer was too small to contains the input
• a timeout occurred when reading from a stream (see How to change the timeout)

Before ArduinoJson 6.17.0, IncompleteInput could also mean “empty input.”

DeserializationError::InvalidInput

The input is not recognized. Possible reasons:

• the input is simply invalid
• the input contains a comment, but support is disabled
• the input is valid but is preceded by something else (see below)
• you called deserializeJson() twice in zero-copy mode

If this error occurs on an HTTP response, ensure your program:

1. skips the HTTP headers
2. uses HTTP version 1.0 or handles chunked transfer encoding

See JsonHttpClient.ino and How to use ArduinoJson with HTTPClient?.

This error also occurs if the input document starts with a byte order mark (BOM). This problem is hard to diagnose because the BOM is an invisible character, so you can’t see it in the Serial Monitor and in most text editors. The easiest way to check if the BOM is present is to read the first byte of the input (for example, you can do Serial.print((char)client.read())). The first character should be a { or a [; if you see something else, then it’s surely the BOM. If that’s your case, you must skip the first two bytes before calling deserializeJson(), like so:

client.read();
client.read();
deserializeJson(doc, client);

Of course, the best solution is still to remove the BOM from the server side.

DeserializationError::NoMemory

The JsonDocument is too small; you need to increase its capacity.

When using a DynamicJsonDocument, it can also mean that the allocation of the memory pool failed.
You can check whether the allocation succeeded by looking at JsonDocument::capacity().

See also:

• How to determine the capacity of the JsonDocument?
• How to deserialize a very large document?

DeserializationError::NotSupported ⚠️ removed

The document included features not supported by the parser. Possible reasons:

• the JSON input contains a Unicode escape sequence (like \u0032), but support is disabled
• the MessagePack input contains a binary value
• the MessagePack input contains an object key that is not a string

NotSupported was removed in ArduinoJson 6.18.0. Instead, deserializeJson() ignores the Unicode escape sequences when ARDUINOJSON_DECODE_UNICODE is 0 (the default is 1 since 6.16), and deserializeMsgPack() replaces unsupported values with nulls.

DeserializationError::TooDeep

The nesting limit was reached; you need to increase its value. See deserializeJson(), or ARDUINOJSON_DEFAULT_NESTING_LIMIT for details.

Methods

// return a string representation of the error
const char* c_str() const;

// same as c_str(), except the string is in Flash memory (only relevant for AVR and ESP8266)
const __FlashStringHelper* f_str() const;

// returns the enum value
Code code() const;

How to know where deserialization stopped?

When you pass a Stream to deserializeJson(), it consumes the input but doesn’t print anything to the serial, which makes troubleshooting difficult.

If you want to see what deserializeJson() consumed, use ReadLoggingStream from the StreamUtils library (see example below). Because ArduinoJson stops reading as soon as it sees an error, you can see what caused the error by checking the last consumed character.

Example

Get the error message

DynamicJsonDocument doc(1024);
DeserializationError err = deserializeJson(doc, "!!NOT JSON!!");
if (err) {
    Serial.print(F("deserializeJson() failed: "))
    Serial.println(err.c_str())
}

the program above prints:

deserializeJson() failed: InvalidInput

Switch/case

DynamicJsonDocument doc(1024);
DeserializationError err = deserializeJson(doc, "!!NOT JSON!!");
switch (err.code()) {
    case DeserializationError::Ok:
        Serial.print(F("Deserialization succeeded"));
        break;
    case DeserializationError::InvalidInput:
        Serial.print(F("Invalid input!"));
        break;
    case DeserializationError::NoMemory:
        Serial.print(F("Not enough memory"));
        break;
    default:
        Serial.print(F("Deserialization failed"));
        break;
}

the program above prints:

Invalid input!

View the content of the input stream

This example requires the StreamUtils library.

Suppose the following line returned InvalidInput:

DeserializationError err = deserializeJson(doc, wifiClient);

If you want to see what caused this error, you can make ArduinoJson log the content of the stream by using a ReadLoggingStream. Replace the above line with:

ReadLoggingStream loggingStream(wifiClient, Serial);
DeserializationError err = deserializeJson(doc, loggingStream);

The first line creates a new Stream on top of wifiClient that writes everything it reads to Serial. Because deserializeJson() stops reading as soon as it sees an error, the last character printed to the serial port is the character that triggered the error.

See also

• deserializeJson()
• deserializeMsgPack()
• Deserialization tutorial