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 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:

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

DeserializationError::InvalidInput

The input is not recognized. Possible reasons:

If this error occurs on an HTTP response, make sure you properly handle chunked transfer encoding or use HTTP version 1.0. For example, if you use ESP8266HTTPClient, make sure you call http.useHTTP10(true) before sending the request.

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 invisible in the Serial Monitor and in many text editors. The easiest way to check if the BOM is present is to read the first byte of the input. The first character should be a { or a [; if you see something else, then it’s surely the BOM.

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 deserialize a very large document?

DeserializationError::NotSupported

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

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