Skip to content

JSON_DIAGNOSTICS

#define JSON_DIAGNOSTICS /* value */

This macro enables extended diagnostics for exception messages. Possible values are 1 to enable or 0 to disable (default).

When enabled, exception messages contain a JSON Pointer to the JSON value that triggered the exception. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.

The diagnostics messages can also be controlled with the CMake option JSON_Diagnostics (OFF by default) which sets JSON_DIAGNOSTICS accordingly.

Default definition

The default value is 0 (extended diagnostics are switched off).

#define JSON_DIAGNOSTICS 0

When the macro is not defined, the library will define it to its default value.

Notes

ABI incompatibility

As this macro changes the definition of the basic_json object, it MUST be defined in the same way globally, even across different compilation units: basic_json objects with differently defined JSON_DIAGNOSTICS macros are not compatible!

Examples

Example 1: default behavior
#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j;
    j["address"]["street"] = "Fake Street";
    j["address"]["housenumber"] = "12";

    try
    {
        int housenumber = j["address"]["housenumber"];
    }
    catch (json::exception& e)
    {
        std::cout << e.what() << '\n';
    }
}

Output:

[json.exception.type_error.302] type must be number, but is string

This exception can be hard to debug if storing the value "12" and accessing it is further apart.

Example 2: extended diagnostic messages
#include <iostream>

# define JSON_DIAGNOSTICS 1
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    json j;
    j["address"]["street"] = "Fake Street";
    j["address"]["housenumber"] = "12";

    try
    {
        int housenumber = j["address"]["housenumber"];
    }
    catch (json::exception& e)
    {
        std::cout << e.what() << '\n';
    }
}

Output:

[json.exception.type_error.302] (/address/housenumber) type must be number, but is string

Now the exception message contains a JSON Pointer /address/housenumber that indicates which value has the wrong type.

Version history

  • Added in version 3.10.0.

Last update: May 1, 2022
Back to top