This commit is contained in:
nlohmann committed 2026-11-09 18:59:22 +00:00
1 parent cf8df97ba7
commit eeea067a72
566 files changed
+15370 -2688

No files matched your search

+7 -7
View File
@@ -1,4 +1,4 @@
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/home/exceptions/" rel="canonical"><link href=../faq/ rel=prev><link href=../releases/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>Exceptions - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.57a0d79d.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.fb2fffe2.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#exceptions class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Exceptions </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79lLine truncated
<!doctype html><html lang=en class=no-js> <head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type."><meta name=author content="Niels Lohmann"><link href="https://json.nlohmann.me/home/exceptions/" rel="canonical"><link href=../faq/ rel=prev><link href=../releases/ rel=next><link rel=icon href=../../assets/images/favicon.png><meta name=generator content="mkdocs-1.6.1, mkdocs-material-9.8.0"><title>Exceptions - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.57a0d79d.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.fb2fffe2.min.css><link rel=stylesheet href=../../css/custom.css><link rel=stylesheet href=../../css/brand.css><link rel=stylesheet href=../../css/fig-sax.css><link rel=stylesheet href=../../css/fig-jsonview.css><link rel=stylesheet href=../../css/fig-exceptions.css><link rel=stylesheet href=../../css/fig-pointer.css><link rel=stylesheet href=../../css/fig-charts.css><link rel=stylesheet href=../../css/fig-integration.css><link rel=stylesheet href=../../css/fig-macros.css><script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,_)=>(e<<5)-e+_.charCodeAt(0)),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script></head> <body dir=ltr data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom> <input class=md-toggle data-md-toggle=drawer type=checkbox id=__drawer autocomplete=off> <input class=md-toggle data-md-toggle=search type=checkbox id=__search autocomplete=off> <label class=md-overlay for=__drawer></label> <div data-md-component=skip> <a href=#exceptions class=md-skip> Skip to content </a> </div> <div data-md-component=announce> </div> <header class=md-header data-md-component=header> <nav class="md-header__inner md-grid" aria-label=Header> <a href=../.. title="JSON for Modern C++" class="md-header__button md-logo" aria-label="JSON for Modern C++" data-md-component=logo> <img src=../../images/wordmark-header.svg alt=logo> </a> <label class="md-header__button md-icon" for=__drawer> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M3 6h18v2H3zm0 5h18v2H3zm0 5h18v2H3z"/></svg> </label> <div class=md-header__title data-md-component=header-title> <div class=md-header__ellipsis> <div class=md-header__topic> <span class=md-ellipsis> JSON for Modern C++ </span> </div> <div class=md-header__topic data-md-component=header-topic> <span class=md-ellipsis> Exceptions </span> </div> </div> </div> <form class=md-header__option data-md-component=palette> <input class=md-option data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme=default data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to dark mode" type=radio name=__palette id=__palette_0> <label class="md-header__button md-icon" title="Switch to dark mode" for=__palette_1 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a4 4 0 0 0-4 4 4 4 0 0 0 4 4 4 4 0 0 0 4-4 4 4 0 0 0-4-4m0 10a6 6 0 0 1-6-6 6 6 0 0 1 6-6 6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> <input class=md-option data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme=slate data-md-color-primary=custom data-md-color-accent=custom aria-label="Switch to light mode" type=radio name=__palette id=__palette_1> <label class="md-header__button md-icon" title="Switch to light mode" for=__palette_0 hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 18c-.89 0-1.74-.2-2.5-.55C11.56 16.5 13 14.42 13 12s-1.44-4.5-3.5-5.45C10.26 6.2 11.11 6 12 6a6 6 0 0 1 6 6 6 6 0 0 1-6 6m8-9.31V4h-4.69L12 .69 8.69 4H4v4.69L.69 12 4 15.31V20h4.69L12 23.31 15.31 20H20v-4.69L23.31 12z"/></svg> </label> </form> <script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script> <label class="md-header__button md-icon" for=__search> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79lLine truncated
S{{"which call?"}} --&gt;|"at(key)"| A{{"j is"}}
A --&gt;|"object, key missing"| A1["out_of_range.403"]
A --&gt;|"array or null"| A2["type_error.304"]
@@ -135,8 +135,8 @@ byte position of error: 8
</code></pre></div></p> </div> <h3 id=jsonexceptionparse_error114>json.exception.parse_error.114<a class=headerlink href=#jsonexceptionparse_error114 title="Permanent link">&para;</a></h3> <p>The parsing of the corresponding <abbr title="Binary JSON">BSON</abbr> record type is not implemented (yet).</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.parse_error.114] parse error at byte 5: Unsupported BSON record type 0xFF
</code></pre></div> </div> <h3 id=jsonexceptionparse_error115>json.exception.parse_error.115<a class=headerlink href=#jsonexceptionparse_error115 title="Permanent link">&para;</a></h3> <p>A <abbr title="Universal Binary JSON">UBJSON</abbr> or <abbr title="Binary JData">BJData</abbr> high-precision number could not be parsed.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>[json.exception.parse_error.115] parse error at byte 5: syntax error while parsing UBJSON high-precision number: invalid number text: 1A
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.parse_error.115] parse error at byte 5: syntax error while parsing BJData high-precision number: invalid number text: 1A
</code></pre></div></p> </div> <h3 id=jsonexceptionparse_error116>json.exception.parse_error.116<a class=headerlink href=#jsonexceptionparse_error116 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/load/ ><code>basic_json_document::load()</code></a> rejected an <a href=../../features/json_view/#images>image</a>: either the bytes are not one <a href=../../api/basic_json_document/save/ ><code>save()</code></a> could have written (too short, an unknown magic number or format version, or sizes that do not fit the buffer), or they are, but fail the requested <a href=../../api/basic_json_document/load/#image_check><code>image_check</code></a>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.parse_error.116] parse error: invalid json_document image: the check failed
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with <a href=../../features/json_view/#images>images</a>.</p> </div> <h2 id=iterator-errors>Iterator errors<a class=headerlink href=#iterator-errors title="Permanent link">&para;</a></h2> <p>This exception is thrown if iterators passed to a library function do not match the expected semantics.</p> <p>Exceptions have ids 2xx.</p> <details class=example> <summary>Example: catch an <code>invalid_iterator</code> exception</summary> <p>The following code shows how an <code>invalid_iterator</code> exception can be caught.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
</code></pre></div></p> </div> <h3 id=jsonexceptionparse_error116>json.exception.parse_error.116<a class=headerlink href=#jsonexceptionparse_error116 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/load/ ><code>basic_json_document::load()</code></a> rejected an <a href=../../features/json_view/images/ >image</a>: either the bytes are not one <a href=../../api/basic_json_document/save/ ><code>save()</code></a> could have written (too short, an unknown magic number or format version, or sizes that do not fit the buffer), or they are, but fail the requested <a href=../../api/basic_json_document/load/#image_check><code>image_check</code></a>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.parse_error.116] parse error: invalid json_document image: the check failed
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with <a href=../../features/json_view/images/ >images</a>.</p> </div> <h2 id=iterator-errors>Iterator errors<a class=headerlink href=#iterator-errors title="Permanent link">&para;</a></h2> <p>This exception is thrown if iterators passed to a library function do not match the expected semantics.</p> <p>Exceptions have ids 2xx.</p> <details class=example> <summary>Example: catch an <code>invalid_iterator</code> exception</summary> <p>The following code shows how an <code>invalid_iterator</code> exception can be caught.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
<span class=k>using</span><span class=w> </span><span class=n>nlohmann</span><span class=o>::</span><span class=n>json</span><span class=p>;</span>
@@ -222,8 +222,8 @@ exception id: 308
</code></pre></div> Serializing <code class=highlight><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=mi>2</span><span class=p>,</span><span class=mi>3</span><span class=p>]</span></code> to <abbr title="Binary JSON">BSON</abbr>: <div class=highlight><pre><span></span><code>[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is array
</code></pre></div></p> </div> <div class="admonition tip"> <p class=admonition-title>Tip</p> <p>Encapsulate the <abbr title="JavaScript Object Notation">JSON</abbr> value in an object. That is, instead of serializing <code class=highlight><span class=kc>true</span></code>, serialize <code class=highlight><span class=p>{</span><span class=nt>"value"</span><span class=p>:</span><span class=w> </span><span class=kc>true</span><span class=p>}</span></code></p> </div> <h3 id=jsonexceptiontype_error318>json.exception.type_error.318<a class=headerlink href=#jsonexceptiontype_error318 title="Permanent link">&para;</a></h3> <p>With <a href=../../api/macros/json_use_objects_for_enum_keyed_maps/ ><code>JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS</code></a>, a map with enum keys is stored as an object. This exception is thrown if two of its keys are converted to the same string, so one of the entries would be lost. This happens, for instance, if <a href=../../api/macros/nlohmann_json_serialize_enum/ ><code>NLOHMANN_JSON_SERIALIZE_ENUM</code></a> does not list an enumerator and it is therefore converted like the first listed one.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.318] duplicate object key 'red'
</code></pre></div> </div> <h3 id=jsonexceptiontype_error319>json.exception.type_error.319<a class=headerlink href=#jsonexceptiontype_error319 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/set/ ><code>basic_json_document::set</code></a>, <a href=../../api/basic_json_document/push_back/ ><code>basic_json_document::push_back</code></a>, and <a href=../../api/basic_json_document/insert/ ><code>basic_json_document::insert</code></a> can store any <code>basic_json</code> value except a binary one: a <code>json_document</code> has no representation for <a href=../../features/binary_values/ >binary values</a>, which only ever arise from parsing a binary format or from an explicit <a href=../../api/basic_json/binary/ ><code>json::binary</code></a> value, not from <abbr title="JavaScript Object Notation">JSON</abbr> text.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.319] cannot store a binary value in a json_document
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with editable <a href=../../features/json_view/ ><code>json_document</code>s</a>.</p> </div> <h3 id=jsonexceptiontype_error320>json.exception.type_error.320<a class=headerlink href=#jsonexceptiontype_error320 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/save/ ><code>basic_json_document::save()</code></a> cannot write an <a href=../../features/json_view/#images>image</a> of a <a href=../../api/basic_json_document/is_discarded/ >discarded</a> document.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.320] cannot save a discarded json_document
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with <a href=../../features/json_view/#images>images</a>.</p> </div> <h3 id=jsonexceptiontype_error321>json.exception.type_error.321<a class=headerlink href=#jsonexceptiontype_error321 title="Permanent link">&para;</a></h3> <p>A discarded value (one created by <a href=../../api/basic_json/parse/ ><code>parse()</code></a> with a callback that returns <code>false</code> for the value, or by default-constructing a <a href=../../api/basic_json/ ><code>basic_json</code></a> with <a href=../../api/basic_json/value_t/ ><code>value_t::discarded</code></a>) was passed to a binary serialization function, either directly or nested in an array or object. There is no way to represent a discarded value in <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>, <abbr title="Binary JData">BJData</abbr>, <abbr title="Binary JSON">BSON</abbr>, or <abbr title="Binary Object Notation 8">BON8</abbr>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Serializing <code class=highlight><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>]</span></code> to <abbr title="Concise Binary Object Representation">CBOR</abbr>, where the second element was discarded by a parser callback: <div class=highlight><pre><span></span><code>[json.exception.type_error.321] cannot serialize discarded value to CBOR
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with editable <a href=../../features/json_view/editing/ ><code>json_document</code>s</a>.</p> </div> <h3 id=jsonexceptiontype_error320>json.exception.type_error.320<a class=headerlink href=#jsonexceptiontype_error320 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/save/ ><code>basic_json_document::save()</code></a> cannot write an <a href=../../features/json_view/images/ >image</a> of a <a href=../../api/basic_json_document/is_discarded/ >discarded</a> document.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <div class=highlight><pre><span></span><code>[json.exception.type_error.320] cannot save a discarded json_document
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with <a href=../../features/json_view/images/ >images</a>.</p> </div> <h3 id=jsonexceptiontype_error321>json.exception.type_error.321<a class=headerlink href=#jsonexceptiontype_error321 title="Permanent link">&para;</a></h3> <p>A discarded value (one created by <a href=../../api/basic_json/parse/ ><code>parse()</code></a> with a callback that returns <code>false</code> for the value, or by default-constructing a <a href=../../api/basic_json/ ><code>basic_json</code></a> with <a href=../../api/basic_json/value_t/ ><code>value_t::discarded</code></a>) was passed to a binary serialization function, either directly or nested in an array or object. There is no way to represent a discarded value in <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, <abbr title="Universal Binary JSON">UBJSON</abbr>, <abbr title="Binary JData">BJData</abbr>, <abbr title="Binary JSON">BSON</abbr>, or <abbr title="Binary Object Notation 8">BON8</abbr>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Serializing <code class=highlight><span class=p>[</span><span class=mi>1</span><span class=p>,</span><span class=w> </span><span class=mi>2</span><span class=p>]</span></code> to <abbr title="Concise Binary Object Representation">CBOR</abbr>, where the second element was discarded by a parser callback: <div class=highlight><pre><span></span><code>[json.exception.type_error.321] cannot serialize discarded value to CBOR
</code></pre></div></p> </div> <h2 id=out-of-range>Out of range<a class=headerlink href=#out-of-range title="Permanent link">&para;</a></h2> <p>This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for instance, in the case of array indices or nonexisting object keys.</p> <p>Exceptions have ids 4xx.</p> <details class=example> <summary>Example: catch an <code>out_of_range</code> exception</summary> <p>The following code shows how an <code>out_of_range</code> exception can be caught.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
<span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;nlohmann/json.hpp&gt;</span>
@@ -269,7 +269,7 @@ exception id: 401
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, this situation was silently ignored (the <code>remove</code> operation had no effect).</p> </div> <h3 id=jsonexceptionout_of_range414>json.exception.out_of_range.414<a class=headerlink href=#jsonexceptionout_of_range414 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch <code>move</code> operation's <code>"from"</code> location is a proper prefix of its <code>"path"</code> location. Per <a href="https://datatracker.ietf.org/doc/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902</a> (section 4.4), a location cannot be moved into one of its own children.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.414] cannot move value: 'from' path '/0' is a proper prefix of 'path' '/0/0'
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, this situation could succeed with a corrupted result: for an array target, removing the "from" element before the "add" step shifted subsequent indices, so "path" silently re-resolved to a different element than intended.</p> </div> <h3 id=jsonexceptionout_of_range415>json.exception.out_of_range.415<a class=headerlink href=#jsonexceptionout_of_range415 title="Permanent link">&para;</a></h3> <p>MessagePack's ext type and <abbr title="Binary JSON">BSON</abbr>'s binary subtype are each stored in a single byte. This exception is thrown when serializing a <a href=../../api/byte_container_with_subtype/ ><code>byte_container_with_subtype</code></a> whose subtype exceeds 255, the largest value the library can store in that byte.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.415] subtype 70000 is too large for the MessagePack ext type (max 255)
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.415] subtype 70000 is too large for the BSON binary subtype (max 255)
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, subtypes above 255 were silently truncated modulo 256 instead of raising an error.</p> </div> <h3 id=jsonexceptionout_of_range416>json.exception.out_of_range.416<a class=headerlink href=#jsonexceptionout_of_range416 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse()</code></a> and the other parsing functions of <a href=../../api/basic_json_document/ ><code>basic_json_document</code></a> index a value's position in the source text in 32 bits, so they do not support an input of 4294967280 bytes (4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes) or more. The same 32-bit limit applies to an <strong>editable</strong> document's own storage: <a href=../../api/basic_json_document/set/ ><code>set</code></a> and <a href=../../api/basic_json_document/push_back/ ><code>push_back</code></a> throw this exception once the strings and number tokens written by edits reach 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> in total, or once more than 4294967295 arrays/objects have had an element set or appended to them. The same limit applies to an <a href=../../features/json_view/#images>image</a>: <a href=../../api/basic_json_document/save/ ><code>save()</code></a> throws it if the node count, the text, or the decoded strings it would write would individually reach 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr>.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>[json.exception.out_of_range.416] input of 4294967280 bytes or more is not supported by json_document
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, subtypes above 255 were silently truncated modulo 256 instead of raising an error.</p> </div> <h3 id=jsonexceptionout_of_range416>json.exception.out_of_range.416<a class=headerlink href=#jsonexceptionout_of_range416 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json_document/parse/ ><code>basic_json_document::parse()</code></a> and the other parsing functions of <a href=../../api/basic_json_document/ ><code>basic_json_document</code></a> index a value's position in the source text in 32 bits, so they do not support an input of 4294967280 bytes (4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> minus 16 bytes) or more. The same 32-bit limit applies to an <strong>editable</strong> document's own storage: <a href=../../api/basic_json_document/set/ ><code>set</code></a> and <a href=../../api/basic_json_document/push_back/ ><code>push_back</code></a> throw this exception once the strings and number tokens written by edits reach 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr> in total, or once more than 4294967295 arrays/objects have had an element set or appended to them. The same limit applies to an <a href=../../features/json_view/images/ >image</a>: <a href=../../api/basic_json_document/save/ ><code>save()</code></a> throws it if the node count, the text, or the decoded strings it would write would individually reach 4 <abbr title="Gibibyte (2^30 bytes)">GiB</abbr>.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>[json.exception.out_of_range.416] input of 4294967280 bytes or more is not supported by json_document
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.416] edits of 4 GiB or more are not supported by json_document
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.416] images of 4 GiB or more are not supported by json_document
</code></pre></div></p> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, together with <a href=../../features/json_view/ ><code>&lt;nlohmann/json_view.hpp&gt;</code></a>. <a href=../../api/basic_json/parse/ ><code>basic_json::parse()</code></a> has no such limit.</p> </div> <h2 id=further-exceptions>Further exceptions<a class=headerlink href=#further-exceptions title="Permanent link">&para;</a></h2> <p>This exception is thrown in case of errors that cannot be classified with the other exception types.</p> <p>Exceptions have ids 5xx.</p> <details class=example> <summary>Example: catch an <code>other_error</code> exception</summary> <p>The following code shows how an <code>other_error</code> exception can be caught.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
@@ -306,4 +306,4 @@ exception id: 401
exception id: 501
</code></pre></div> </details> <h3 id=jsonexceptionother_error501>json.exception.other_error.501<a class=headerlink href=#jsonexceptionother_error501 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch operation 'test' failed. The unsuccessful operation is also printed.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p>Executing <code class=highlight><span class=p>{</span><span class=nt>"op"</span><span class=p>:</span><span class=s2>"test"</span><span class=p>,</span><span class=w> </span><span class=nt>"path"</span><span class=p>:</span><span class=s2>"/baz"</span><span class=p>,</span><span class=w> </span><span class=nt>"value"</span><span class=p>:</span><span class=s2>"bar"</span><span class=p>}</span></code> on <code class=highlight><span class=p>{</span><span class=nt>"baz"</span><span class=p>:</span><span class=w> </span><span class=s2>"qux"</span><span class=p>}</span></code>:</p> <div class=highlight><pre><span></span><code>[json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
</code></pre></div> </div> <h3 id=jsonexceptionother_error502>json.exception.other_error.502<a class=headerlink href=#jsonexceptionother_error502 title="Permanent link">&para;</a></h3> <p><a href=../../api/basic_json/to_ubjson/ ><code>to_ubjson</code></a> and <a href=../../api/basic_json/to_bjdata/ ><code>to_bjdata</code></a> were called with <code>use_type = true</code> but <code>use_size = false</code>, and the value contains a non-empty array or object (or, with <abbr title="Binary JData">BJData</abbr> Draft 3, any binary value). <abbr title="Universal Binary JSON">UBJSON</abbr> requires a size marker (<code>#</code>) after a type marker (<code>$</code>); scalars and empty arrays or objects do not throw.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.other_error.502] use_type requires use_size = true
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, debug builds aborted on an assertion and release builds wrote a <code>$</code> marker without <code>#</code>, which <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> then rejected.</p> </div> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/exception/ ><code>exception</code></a> - base class of all exceptions thrown by the library</li> <li><a href=../../api/basic_json/parse_error/ ><code>parse_error</code></a> - exceptions indicating a parse error</li> <li><a href=../../api/basic_json/invalid_iterator/ ><code>invalid_iterator</code></a> - exceptions indicating errors with iterators</li> <li><a href=../../api/basic_json/type_error/ ><code>type_error</code></a> - exceptions indicating a wrong type</li> <li><a href=../../api/basic_json/out_of_range/ ><code>out_of_range</code></a> - exceptions indicating access out of range</li> <li><a href=../../api/basic_json/other_error/ ><code>other_error</code></a> - exceptions indicating other library errors</li> <li><a href=../../api/macros/json_noexception/ ><code>JSON_NOEXCEPTION</code></a> - switch off exceptions</li> <li><a href=../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> - extended exception messages with the path of the failing value</li> <li><a href=../../features/no_exceptions/ >Working Without Exceptions</a> - use the library without exceptions</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="October 27, 2026 06:41:42 UTC">October 27, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../faq/ class="md-footer__link md-footer__link--prev" aria-label="Previous: FAQ"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> FAQ </div> </div> </a> <a href=../releases/ class="md-footer__link md-footer__link--next" aria-label="Next: Overview"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Overview </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 Line truncated
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception was added in version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>. Before that, debug builds aborted on an assertion and release builds wrote a <code>$</code> marker without <code>#</code>, which <a href=../../api/basic_json/from_ubjson/ ><code>from_ubjson</code></a> then rejected.</p> </div> <h2 id=see-also>See also<a class=headerlink href=#see-also title="Permanent link">&para;</a></h2> <ul> <li><a href=../../api/basic_json/exception/ ><code>exception</code></a> - base class of all exceptions thrown by the library</li> <li><a href=../../api/basic_json/parse_error/ ><code>parse_error</code></a> - exceptions indicating a parse error</li> <li><a href=../../api/basic_json/invalid_iterator/ ><code>invalid_iterator</code></a> - exceptions indicating errors with iterators</li> <li><a href=../../api/basic_json/type_error/ ><code>type_error</code></a> - exceptions indicating a wrong type</li> <li><a href=../../api/basic_json/out_of_range/ ><code>out_of_range</code></a> - exceptions indicating access out of range</li> <li><a href=../../api/basic_json/other_error/ ><code>other_error</code></a> - exceptions indicating other library errors</li> <li><a href=../../api/macros/json_noexception/ ><code>JSON_NOEXCEPTION</code></a> - switch off exceptions</li> <li><a href=../../api/macros/json_diagnostics/ ><code>JSON_DIAGNOSTICS</code></a> - extended exception messages with the path of the failing value</li> <li><a href=../../features/no_exceptions/ >Working Without Exceptions</a> - use the library without exceptions</li> </ul> <!-- https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-a-glossary --> <aside class=md-source-file> <span class=md-source-file__fact> <span class=md-icon title="Last update"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M21 13.1c-.1 0-.3.1-.4.2l-1 1 2.1 2.1 1-1c.2-.2.2-.6 0-.8l-1.3-1.3c-.1-.1-.2-.2-.4-.2m-1.9 1.8-6.1 6V23h2.1l6.1-6.1zM12.5 7v5.2l4 2.4-1 1L11 13V7zM11 21.9c-5.1-.5-9-4.8-9-9.9C2 6.5 6.5 2 12 2c5.3 0 9.6 4.1 10 9.3-.3-.1-.6-.2-1-.2s-.7.1-1 .2C19.6 7.2 16.2 4 12 4c-4.4 0-8 3.6-8 8 0 4.1 3.1 7.5 7.1 7.9l-.1.2z"/></svg> </span> <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-date" title="November 9, 2026 07:12:00 UTC">November 9, 2026</span> </span> </aside> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type=button class="md-top md-icon" data-md-component=top hidden> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class=md-footer> <nav class="md-footer__inner md-grid" aria-label=Footer> <a href=../faq/ class="md-footer__link md-footer__link--prev" aria-label="Previous: FAQ"> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class=md-footer__title> <span class=md-footer__direction> Previous </span> <div class=md-ellipsis> FAQ </div> </div> </a> <a href=../releases/ class="md-footer__link md-footer__link--next" aria-label="Next: Overview"> <div class=md-footer__title> <span class=md-footer__direction> Next </span> <div class=md-ellipsis> Overview </div> </div> <div class="md-footer__button md-icon"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class=md-copyright> <div class=md-copyright__highlight> Copyright &copy; 2013-2026 Niels Lohmann </div> </div> <div class=md-social> <a href="https://github.com/nlohmann" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 512 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2025 Fonticons, Inc.--><path d="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 Line truncated