JSON_RECURSION_DEPTH_LIMIT¶

#define JSON_RECURSION_DEPTH_LIMIT /* value */

This macro sets how many nesting levels the operations that walk a value recurse into on the call stack. Beyond that, they continue with an explicit stack on the heap. The value is an integer constant from 0 to 254; the default is 128.

The operations are copying a value, comparing two values, serializing with dump or operator<<, hashing with std::hash, merge_patch, update with merge_objects, diff, merge_diff, converting a value to another specialization of basic_json, destroying a value, and the binary writers to_cbor, to_msgpack, to_ubjson, to_bjdata, and to_bon8. They share this one limit; none has a limit of its own. Recursing is the fastest way to walk a value, but a value nested deeply enough would exhaust the call stack, so the library recurses only as far as the limit and finishes the levels below with an explicit stack. This is what makes all of them safe for untrusted input (see Nesting depth). Parsing, the binary readers, flatten, unflatten, and to_bson always use an explicit stack and do not depend on the macro. The lockstep comparison of two json_view documents has a fixed bound of its own, 48 levels, and does not depend on it either.

The call stack that these operations need grows with the limit: roughly a few kilobytes plus a cost per level times the limit, where the cost per level is up to about 2.3 KiB in an unoptimized and up to about 0.5 KiB in an optimized build (see Stack needed). The default of 128 levels is tuned for threads with ordinary stacks of a few hundred kilobytes or more. Set a lower limit if your threads have small stacks (RTOS tasks, fibers, threads of the musl C library, which has a default stack of 128 KiB), or a higher limit to trade stack for speed on deeply nested values.

The macro changes only how much stack is used and how fast the operations are. It never changes a result: every operation returns the same value for every setting of the limit, for values nested less deeply than the limit as well as for values nested more deeply.

Default definition¶

The default value is 128.

#define JSON_RECURSION_DEPTH_LIMIT 128

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

Notes¶

Stack needed¶

The tables show the smallest stack that an operation needs, in KiB, at several limits, on a value that is nested more deeply than the limit (limit + 10 levels). Each cell shows the result for Clang (Apple clang 21) and for GCC 16, separated by a slash; both measured on macOS with arm64, compiling in C++20 mode. The operations run in a thread whose stack has the size given, and are not given any stack that they do not need: the value is built, and the result destroyed, outside of that thread. Stacks can only be set in steps of 16 KiB (the page size), so 16 means "16 KiB or less". A row stands for all operations listed; the table shows the largest value among them.

Unoptimized (-O0):

Optimized (-O2):

With a limit of 0, every operation in the tables ran in a 16 KiB stack at -O0 (Clang and GCC), on a value nested 20,000 levels deep. The operations that do not depend on the macro (flatten, unflatten, to_bson) needed 16 KiB or less at every limit.

The rule of thumb is

stack needed ≈ a few KiB + cost per level × limit

with a cost per level of up to 2.3 KiB (dump at -O0 with Clang; 2.1 KiB with GCC), 1.7 KiB for copying and merging (1.3 KiB with GCC), and 0.1 to 0.5 KiB for most other operations at -O0; and 0.5 KiB or less at -O2. The numbers come from the difference between the limits 128 and 254 in the tables, so they are rough: other compilers, other targets (the frames of x86-64 code are about as large), other standard libraries, JSON_DIAGNOSTICS, and sanitizers change them. Measure with your own tool chain (see the example below) rather than relying on the tables. The stack that your own code and the operating system need comes on top of these numbers.

Which limit to choose, for the stack that you can spare for the library (the largest limit of those measured for which the slowest operation needs at most that much):

Speed¶

Operations are faster the more of a value they handle with plain recursion. The levels below the limit are handled with an explicit stack, which has to be kept on the heap and costs more per level. The macro therefore trades speed against stack.

The table shows the time of copying a value (including destroying the copy), of == on two equal values, of dump, and of std::hash for several limits, relative to the default of 128 (1.00 means the same time; more is slower). It was measured with Clang 21 at -O2 in C++17 mode on macOS with arm64, as the best of seven runs of each setting (two rounds, best of both). The documents are ordinary JSON files that are nested 7 (canada.json), 8 (citm_catalog.json), 10 (twitter.json), and 2 levels deep (jeopardy.json); the other values are one array or object with one member per level, nested 1,000 and 100,000 levels deep. The absolute time at the limit 128 is given in the third column. Differences of up to about 0.1 are noise: a different limit changes the layout of the compiled code, and timings of the same binary vary by about as much. The slow columns (limits 0 and 1) vary more: repeating std::hash on canada.json gave 1.27 to 1.30 for limit 0 and 1.4 to 1.9 for limit 1, so read the cells of those two columns as accurate to about 0.3.

The results are as follows.

• A limit of 16 or more does not change the speed of ordinary documents (differences are within noise), because they are not nested more deeply than that anyway. A document nested more deeply than the limit is walked partly with the explicit stack.
• A limit of 0 or 1 makes the operations on ordinary documents 1.1 to 2.4 times as slow, because even their first levels are handled with the explicit stack. The slowdown is largest for == on a document of many small containers (canada.json: 2.4 times) and for copying (up to 1.8 times).
• For values that are nested far more deeply than any limit (1,000 and 100,000 levels deep), the limit makes no measurable difference: almost all of the levels are handled with the explicit stack for every setting. Raising the limit gains nothing for them, and lowering it costs nothing.

Examples¶

#include <functional>
#include <iostream>
#include <utility>

// walk over at most 16 nesting levels on the call stack, and over the rest with an explicit stack
#define JSON_RECURSION_DEPTH_LIMIT 16
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // an array nested 5,000 levels deep, built without recursion
    json j = 1;
    for (int i = 0; i < 5000; ++i)
    {
        json outer = json::array();
        outer.push_back(std::move(j));
        j = std::move(outer);
    }

    // the results are those of any other limit
    const json copy = j;
    std::cout << std::boolalpha;
    std::cout << "limit: " << JSON_RECURSION_DEPTH_LIMIT << '\n';
    std::cout << "copy equals original: " << (copy == j) << '\n';
    std::cout << "length of dump(): " << j.dump().size() << '\n';
    std::cout << "same hash: " << (std::hash<json> {}(copy) == std::hash<json> {}(j)) << '\n';
}

limit: 16
copy equals original: true
length of dump(): 10001
same hash: true

#include <cstdlib>
#include <iostream>
#include <string>
#include <utility>
#include <pthread.h>
#include <nlohmann/json.hpp>

static nlohmann::json value;

static void* run(void*)
{
    std::cout << "dump() ok, " << value.dump().size() << " bytes\n";
    return nullptr;
}

int main(int argc, char** argv)
{
    const int depth = std::atoi(argv[1]);
    const std::size_t kib = static_cast<std::size_t>(std::atoi(argv[2]));

    // built on the main thread, without recursion
    value = 1;
    for (int i = 0; i < depth; ++i)
    {
        nlohmann::json outer = nlohmann::json::array();
        outer.push_back(std::move(value));
        value = std::move(outer);
    }

    pthread_attr_t attr;
    pthread_attr_init(&attr);
    pthread_attr_setstacksize(&attr, kib * 1024);
    pthread_t thread;
    pthread_create(&thread, &attr, run, nullptr);
    pthread_join(thread, nullptr);
}

See also¶

• Nesting depth - how the library handles deeply nested values
• JSON_NO_THREAD_LOCAL - switch off the use of thread_local storage
• Supported Macros - guide to all supported macros

Version history¶

• Added in version 3.13.0 unreleased.