This commit is contained in:
nlohmann committed 2026-10-27 12:14:00 +00:00
1 parent b36f8a9821
commit 11a863958e
1180 files changed
+14211 -6025

No files matched your search

+34 -46
View File
@@ -1,29 +1,17 @@
<!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=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.7.7"><title>Exceptions - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.min.css><link rel="stylesheet" href="../../assets/external/fonts.googleapis.com/css.61a430c9.css"><style>:root{--md-text-font:"Roboto";--md-code-font:"JetBrains Mono"}</style><link rel=stylesheet href=../../css/custom.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=indigo data-md-color-accent=indigo> <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> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 24 24"><path d="M12 8a3 3 0 0 0 3-3 3 3 0 0 0-3-3 3 3 0 0 0-3 3 3 3 0 0 0 3 3m0 3.54C9.64 9.35 6.5 8 3 8v11c3.5 0 6.64 1.35 9 3.54 2.36-2.19 5.5-3.54 9-3.54V8c-3.5 0-6.64 1.35-9 3.54"/></svg> </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=indigo data-md-color-accent=indigo 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=indigo data-md-color-accent=indigo 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-.79l-.27-.27A6.52 6.52 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5"/></svg> </label> <div class=md-search data-md-componLine truncated
direction LR
class `std::exception` {
&lt;&lt;interface&gt;&gt;
}
class `json::exception` {
+const int id
+const char* what() const
}
class `json::parse_error` {
+const std::size_t byte
}
class `json::invalid_iterator`
class `json::type_error`
class `json::out_of_range`
class `json::other_error`
`std::exception` &lt;|-- `json::exception`
`json::exception` &lt;|-- `json::parse_error`
`json::exception` &lt;|-- `json::invalid_iterator`
`json::exception` &lt;|-- `json::type_error`
`json::exception` &lt;|-- `json::out_of_range`
`json::exception` &lt;|-- `json::other_error`</code></pre> <h3 id=switch-off-exceptions>Switch off exceptions<a class=headerlink href=#switch-off-exceptions title="Permanent link">&para;</a></h3> <p>Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag <code>-fno-exceptions</code> or by defining the symbol <a href=../../api/macros/json_noexception/ ><code>JSON_NOEXCEPTION</code></a>. In this case, exceptions are replaced by <code>abort()</code> calls. You can further control this behavior by defining <code>JSON_THROW_USER</code> (overriding <code class=highlight><span class=k>throw</span></code>), <code>JSON_TRY_USER</code> (overriding <code class=highlight><span class=k>try</span></code>), and <code>JSON_CATCH_USER</code> (overriding <code class=highlight><span class=k>catch</span></code>).</p> <p>See <a href=../../features/no_exceptions/ >Working without exceptions</a> for the functions that report errors without throwing.</p> <p>Note that <a href=../../api/macros/json_throw_user/ ><code>JSON_THROW_USER</code></a> should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.</p> <details class=example> <summary>Example: switch off exceptions and log errors before aborting</summary> <p>The code below switches off exceptions and creates a log entry with a detailed error message in case of errors.</p> <div class=highlight><pre><span></span><code><span class=cp>#include</span><span class=w> </span><span class=cpf>&lt;iostream&gt;</span>
<!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.7.7"><title>Exceptions - JSON for Modern C++</title><link rel=stylesheet href=../../assets/stylesheets/main.ec1eaa64.min.css><link rel=stylesheet href=../../assets/stylesheets/palette.ab4e12ef.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"]
S --&gt;|"at(index)"| B{{"j is"}}
B --&gt;|"array, index &gt;= size()"| B1["out_of_range.401"]
B --&gt;|"object or null"| B2["type_error.304"]
S --&gt;|"non-const operator[](key)"| C{{"j is"}}
C --&gt;|"object or null"| C1["no exception: a missing key is inserted as null"]
C --&gt;|"array"| C2["type_error.305"]
S --&gt;|"value(key, default)"| D{{"j is"}}
D --&gt;|"object, key missing"| D1["no exception: returns the default"]
D --&gt;|"object, incompatible value type"| D2["type_error.302"]
D --&gt;|"array or null"| D3["type_error.306"]</code></pre> <p class=nj-caption>Exceptions thrown by element access. Start at the call on the left, follow the edge that matches the type of <code>j</code>, and read the exception id (or "no exception") in the box at the end.</p> <h3 id=switch-off-exceptions>Switch off exceptions<a class=headerlink href=#switch-off-exceptions title="Permanent link">&para;</a></h3> <p>Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag <code>-fno-exceptions</code> or by defining the symbol <a href=../../api/macros/json_noexception/ ><code>JSON_NOEXCEPTION</code></a>. In this case, exceptions are replaced by <code>abort()</code> calls. You can further control this behavior by defining <code>JSON_THROW_USER</code> (overriding <code class=highlight><span class=k>throw</span></code>), <code>JSON_TRY_USER</code> (overriding <code class=highlight><span class=k>try</span></code>), and <code>JSON_CATCH_USER</code> (overriding <code class=highlight><span class=k>catch</span></code>).</p> <p>See <a href=../../features/no_exceptions/ >Working without exceptions</a> for the functions that report errors without throwing.</p> <p>Note that <a href=../../api/macros/json_throw_user/ ><code>JSON_THROW_USER</code></a> should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.</p> <details class=example> <summary>Example: switch off exceptions and log errors before aborting</summary> <p>The code below switches off exceptions and creates a log entry with a detailed error message in case of errors.</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>#define JSON_TRY_USER if(true)</span>
<span class=cp>#define JSON_CATCH_USER(exception) if(false)</span>
@@ -116,8 +104,8 @@ byte position of error: 8
<span class=w> </span><span class=k>return</span><span class=w> </span><span class=mi>1</span><span class=p>;</span>
<span class=p>}</span>
<span class=n>json</span><span class=w> </span><span class=n>data</span><span class=w> </span><span class=o>=</span><span class=w> </span><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=n>f</span><span class=p>);</span>
</code></pre></div> </details> <h3 id=jsonexceptionparse_error102>json.exception.parse_error.102<a class=headerlink href=#jsonexceptionparse_error102 title="Permanent link">&para;</a></h3> <p><abbr title="JavaScript Object Notation">JSON</abbr> uses the <code>\uxxxx</code> format to describe Unicode characters. Code points above 0xFFFF are split into two <code>\uxxxx</code> entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>parse error at 14: missing or wrong low surrogate
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception is not used any more. Instead <a href=#jsonexceptionparse_error101>json.exception.parse_error.101</a> with a more detailed description is used.</p> </div> <h3 id=jsonexceptionparse_error103>json.exception.parse_error.103<a class=headerlink href=#jsonexceptionparse_error103 title="Permanent link">&para;</a></h3> <p>Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>parse error: code points above 0x10FFFF are invalid
</code></pre></div> </details> <h3 id=jsonexceptionparse_error102>json.exception.parse_error.102<a class=headerlink href=#jsonexceptionparse_error102 title="Permanent link">&para;</a></h3> <p><abbr title="JavaScript Object Notation">JSON</abbr> uses the <code>\uxxxx</code> format to describe Unicode characters. Code points above 0xFFFF are split into two <code>\uxxxx</code> entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.parse_error.102] parse error at 14: missing or wrong low surrogate
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception is not used any more. Instead <a href=#jsonexceptionparse_error101>json.exception.parse_error.101</a> with a more detailed description is used.</p> </div> <h3 id=jsonexceptionparse_error103>json.exception.parse_error.103<a class=headerlink href=#jsonexceptionparse_error103 title="Permanent link">&para;</a></h3> <p>Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.parse_error.103] parse error: code points above 0x10FFFF are invalid
</code></pre></div> </div> <div class="admonition note"> <p class=admonition-title>Note</p> <p>This exception is not used any more. Instead <a href=#jsonexceptionparse_error101>json.exception.parse_error.101</a> with a more detailed description is used.</p> </div> <h3 id=jsonexceptionparse_error104>json.exception.parse_error.104<a class=headerlink href=#jsonexceptionparse_error104 title="Permanent link">&para;</a></h3> <p><a href="https://tools.ietf.org/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902</a> requires a <abbr title="JavaScript Object Notation">JSON</abbr> Patch document to be a <abbr title="JavaScript Object Notation">JSON</abbr> document that represents an array of objects.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.parse_error.104] parse error: JSON patch must be an array of objects
</code></pre></div> </div> <h3 id=jsonexceptionparse_error105>json.exception.parse_error.105<a class=headerlink href=#jsonexceptionparse_error105 title="Permanent link">&para;</a></h3> <p>An operation of a <abbr title="JavaScript Object Notation">JSON</abbr> Patch document must contain exactly one "op" member, whose value indicates the operation to perform. Its value must be one of "add", "remove", "replace", "move", "copy", or "test"; other values are errors.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <p><div class=highlight><pre><span></span><code>[json.exception.parse_error.105] parse error: operation 'add' must have member 'value'
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.parse_error.105] parse error: operation 'copy' must have string member 'from'
@@ -258,27 +246,27 @@ exception id: 308
<span class=p>}</span>
</code></pre></div> <p>Output:</p> <div class=highlight><pre><span></span><code>message: [json.exception.out_of_range.401] array index 4 is out of range
exception id: 401
</code></pre></div> </details> <h3 id=jsonexceptionout_of_range401>json.exception.out_of_range.401<a class=headerlink href=#jsonexceptionout_of_range401 title="Permanent link">&para;</a></h3> <p>The provided array index <code>i</code> is larger than <code>size-1</code>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>array index 3 is out of range
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range402>json.exception.out_of_range.402<a class=headerlink href=#jsonexceptionout_of_range402 title="Permanent link">&para;</a></h3> <p>The special array index <code>-</code> in a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer never describes a valid element of the array, but the index past the end. That is, it can only be used to add elements at this position, but not to read it.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>array index '-' (3) is out of range
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range403>json.exception.out_of_range.403<a class=headerlink href=#jsonexceptionout_of_range403 title="Permanent link">&para;</a></h3> <p>The provided key was not found in the <abbr title="JavaScript Object Notation">JSON</abbr> object.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>key 'foo' not found
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range404>json.exception.out_of_range.404<a class=headerlink href=#jsonexceptionout_of_range404 title="Permanent link">&para;</a></h3> <p>A reference token in a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer could not be resolved, for instance an array index that begins with a digit but contains other characters (e.g., <code>1a</code>), or <code>-</code> where it cannot be used.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>unresolved reference token 'foo'
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range405>json.exception.out_of_range.405<a class=headerlink href=#jsonexceptionout_of_range405 title="Permanent link">&para;</a></h3> <p>The <abbr title="JavaScript Object Notation">JSON</abbr> Patch operations 'remove' and 'move' cannot be applied to the root element of the <abbr title="JavaScript Object Notation">JSON</abbr> value. The exception is also thrown when the parent or a reference token of an empty <abbr title="JavaScript Object Notation">JSON</abbr> Pointer is requested, for instance by <a href=../../api/json_pointer/back/ ><code>back</code></a> or <a href=../../api/json_pointer/pop_back/ ><code>pop_back</code></a>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>JSON pointer has no parent
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range406>json.exception.out_of_range.406<a class=headerlink href=#jsonexceptionout_of_range406 title="Permanent link">&para;</a></h3> <p>A parsed number could not be stored without changing it to <abbr title="Not a Number">NaN</abbr> or INF. For the binary formats, this happens when a finite floating-point number does not fit into <a href=../../api/basic_json/number_float_t/ ><code>number_float_t</code></a>, for example a double-precision number when <code>number_float_t</code> is <code class=highlight><span class=kt>float</span></code>.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>number overflow parsing '10E1000'
</code></pre></div> </details> <h3 id=jsonexceptionout_of_range401>json.exception.out_of_range.401<a class=headerlink href=#jsonexceptionout_of_range401 title="Permanent link">&para;</a></h3> <p>The provided array index <code>i</code> is larger than <code>size-1</code>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.401] array index 3 is out of range
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range402>json.exception.out_of_range.402<a class=headerlink href=#jsonexceptionout_of_range402 title="Permanent link">&para;</a></h3> <p>The special array index <code>-</code> in a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer never describes a valid element of the array, but the index past the end. That is, it can only be used to add elements at this position, but not to read it.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.402] array index '-' (3) is out of range
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range403>json.exception.out_of_range.403<a class=headerlink href=#jsonexceptionout_of_range403 title="Permanent link">&para;</a></h3> <p>The provided key was not found in the <abbr title="JavaScript Object Notation">JSON</abbr> object.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.403] key 'foo' not found
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range404>json.exception.out_of_range.404<a class=headerlink href=#jsonexceptionout_of_range404 title="Permanent link">&para;</a></h3> <p>A reference token in a <abbr title="JavaScript Object Notation">JSON</abbr> Pointer could not be resolved, for instance an array index that begins with a digit but contains other characters (e.g., <code>1a</code>), or <code>-</code> where it cannot be used.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.404] unresolved reference token 'foo'
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range405>json.exception.out_of_range.405<a class=headerlink href=#jsonexceptionout_of_range405 title="Permanent link">&para;</a></h3> <p>The <abbr title="JavaScript Object Notation">JSON</abbr> Patch operations 'remove' and 'move' cannot be applied to the root element of the <abbr title="JavaScript Object Notation">JSON</abbr> value. The exception is also thrown when the parent or a reference token of an empty <abbr title="JavaScript Object Notation">JSON</abbr> Pointer is requested, for instance by <a href=../../api/json_pointer/back/ ><code>back</code></a> or <a href=../../api/json_pointer/pop_back/ ><code>pop_back</code></a>.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.405] JSON pointer has no parent
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range406>json.exception.out_of_range.406<a class=headerlink href=#jsonexceptionout_of_range406 title="Permanent link">&para;</a></h3> <p>A parsed number could not be stored without changing it to <abbr title="Not a Number">NaN</abbr> or INF. For the binary formats, this happens when a finite floating-point number does not fit into <a href=../../api/basic_json/number_float_t/ ><code>number_float_t</code></a>, for example a double-precision number when <code>number_float_t</code> is <code class=highlight><span class=kt>float</span></code>.</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.406] number overflow parsing '10E1000'
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.406] syntax error while parsing CBOR value: number overflow
</code></pre></div></p> </div> <h3 id=jsonexceptionout_of_range407>json.exception.out_of_range.407<a class=headerlink href=#jsonexceptionout_of_range407 title="Permanent link">&para;</a></h3> <p>An integer number cannot be represented by the binary format it is serialized to:</p> <ul> <li><a href=../../features/binary_formats/bon8/ ><abbr title="Binary Object Notation 8">BON8</abbr></a> only stores integers that fit into int64, so <a href=../../api/basic_json/to_bon8/ ><code>to_bon8</code></a> throws for unsigned integers greater than 9223372036854775807 and, with a number type wider than 64 bits, for any integer outside the int64 range.</li> <li><a href=../../features/binary_formats/cbor/ ><abbr title="Concise Binary Object Representation">CBOR</abbr></a>, <a href=../../features/binary_formats/messagepack/ >MessagePack</a>, and <a href=../../features/binary_formats/bson/ ><abbr title="Binary JSON">BSON</abbr></a> store integers in at most 64 bits. With the default number types, every integer fits, but a <a href=../../api/basic_json/number_integer_t/ ><code>number_integer_t</code></a> or <a href=../../api/basic_json/number_unsigned_t/ ><code>number_unsigned_t</code></a> wider than 64 bits (e.g., <code>__int128</code>) can hold values outside the range of the format: [-2^64, 2^64-1] for <abbr title="Concise Binary Object Representation">CBOR</abbr>, [-2^63, 2^64-1] for MessagePack, and the range of int64 (signed integers) or uint64 (unsigned integers) for <abbr title="Binary JSON">BSON</abbr>.</li> </ul> <p><a href=../../features/binary_formats/ubjson/ ><abbr title="Universal Binary JSON">UBJSON</abbr></a> and <a href=../../features/binary_formats/bjdata/ ><abbr title="Binary JData">BJData</abbr></a> never throw this exception, because they serialize integers beyond 64 bits as high-precision numbers.</p> <div class="admonition note"> <p class=admonition-title>Former occurrences</p> <p>The <abbr title="Universal Binary JSON">UBJSON</abbr> and <abbr title="Binary JSON">BSON</abbr> writers used to throw this exception as well:</p> <ul> <li>Since version 3.9.0, integer numbers beyond int64 are serialized as high-precision <abbr title="Universal Binary JSON">UBJSON</abbr> numbers.</li> <li>Since version 3.12.0, integer numbers beyond int64 are serialized as uint64 <abbr title="Binary JSON">BSON</abbr> numbers.</li> </ul> <p>Before version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, and <abbr title="Binary JSON">BSON</abbr> silently truncated integers wider than 64 bits, and <abbr title="Binary JData">BJData</abbr> truncated unsigned integers wider than 64 bits that were elements of ND-arrays with <code>"_ArrayType_": "uint64"</code>.</p> </div> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
</code></pre></div> <div class=highlight><pre><span></span><code>integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
</code></pre></div></p> </div> <h3 id=jsonexceptionout_of_range408>json.exception.out_of_range.408<a class=headerlink href=#jsonexceptionout_of_range408 title="Permanent link">&para;</a></h3> <p>The size of an array or object in a <a href=../../features/binary_formats/ >binary format</a> exceeds the maximal capacity: the size following <code>#</code> for <a href=../../features/binary_formats/ubjson/ ><abbr title="Universal Binary JSON">UBJSON</abbr></a>/<a href=../../features/binary_formats/bjdata/ ><abbr title="Binary JData">BJData</abbr></a>, or the encoded length for <a href=../../features/binary_formats/cbor/ ><abbr title="Concise Binary Object Representation">CBOR</abbr></a>.</p> <p>The exception is also thrown for a <a href=../../features/binary_formats/ubjson/ ><abbr title="Universal Binary JSON">UBJSON</abbr></a> array of a type that is encoded by its marker alone (<code>Z</code>, <code>T</code> or <code>F</code>) whose declared count exceeds 1,048,576 (<code>1 &lt;&lt; 20</code>). Such an array has no payload, so its count alone decides how much memory is allocated, and a handful of bytes would otherwise describe billions of values. <a href=../../api/basic_json/to_ubjson/ ><code>to_ubjson</code></a> writes longer arrays of these types without the <code>$</code> type annotation (the <code>#</code> count and one marker per element are kept), so any value it produces can still be read back.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>excessive array size: 8658170730974374167
</code></pre></div></p> </div> <h3 id=jsonexceptionout_of_range407>json.exception.out_of_range.407<a class=headerlink href=#jsonexceptionout_of_range407 title="Permanent link">&para;</a></h3> <p>An integer number cannot be represented by the binary format it is serialized to:</p> <ul> <li><a href=../../features/binary_formats/bon8/ ><abbr title="Binary Object Notation 8">BON8</abbr></a> only stores integers that fit into int64, so <a href=../../api/basic_json/to_bon8/ ><code>to_bon8</code></a> throws for unsigned integers greater than 9223372036854775807 and, with a number type wider than 64 bits, for any integer outside the int64 range.</li> <li><a href=../../features/binary_formats/cbor/ ><abbr title="Concise Binary Object Representation">CBOR</abbr></a>, <a href=../../features/binary_formats/messagepack/ >MessagePack</a>, and <a href=../../features/binary_formats/bson/ ><abbr title="Binary JSON">BSON</abbr></a> store integers in at most 64 bits. With the default number types, every integer fits, but a <a href=../../api/basic_json/number_integer_t/ ><code>number_integer_t</code></a> or <a href=../../api/basic_json/number_unsigned_t/ ><code>number_unsigned_t</code></a> wider than 64 bits (e.g., <code>__int128</code>) can hold values outside the range of the format: [-2^64, 2^64-1] for <abbr title="Concise Binary Object Representation">CBOR</abbr>, [-2^63, 2^64-1] for MessagePack, and the range of int64 (signed integers) or uint64 (unsigned integers) for <abbr title="Binary JSON">BSON</abbr>.</li> </ul> <p><a href=../../features/binary_formats/ubjson/ ><abbr title="Universal Binary JSON">UBJSON</abbr></a> and <a href=../../features/binary_formats/bjdata/ ><abbr title="Binary JData">BJData</abbr></a> never throw this exception, because they serialize integers beyond 64 bits as high-precision numbers.</p> <div class="admonition note"> <p class=admonition-title>Former occurrences</p> <p>The <abbr title="Universal Binary JSON">UBJSON</abbr> and <abbr title="Binary JSON">BSON</abbr> writers used to throw this exception as well:</p> <ul> <li>Since version 3.9.0, integer numbers beyond int64 are serialized as high-precision <abbr title="Universal Binary JSON">UBJSON</abbr> numbers.</li> <li>Since version 3.12.0, integer numbers beyond int64 are serialized as uint64 <abbr title="Binary JSON">BSON</abbr> numbers.</li> </ul> <p>Before version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, <abbr title="Concise Binary Object Representation">CBOR</abbr>, MessagePack, and <abbr title="Binary JSON">BSON</abbr> silently truncated integers wider than 64 bits, and <abbr title="Binary JData">BJData</abbr> truncated unsigned integers wider than 64 bits that were elements of ND-arrays with <code>"_ArrayType_": "uint64"</code>.</p> </div> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>[json.exception.out_of_range.407] integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.407] integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
</code></pre></div></p> </div> <h3 id=jsonexceptionout_of_range408>json.exception.out_of_range.408<a class=headerlink href=#jsonexceptionout_of_range408 title="Permanent link">&para;</a></h3> <p>The size of an array or object in a <a href=../../features/binary_formats/ >binary format</a> exceeds the maximal capacity: the size following <code>#</code> for <a href=../../features/binary_formats/ubjson/ ><abbr title="Universal Binary JSON">UBJSON</abbr></a>/<a href=../../features/binary_formats/bjdata/ ><abbr title="Binary JData">BJData</abbr></a>, or the encoded length for <a href=../../features/binary_formats/cbor/ ><abbr title="Concise Binary Object Representation">CBOR</abbr></a>.</p> <p>The exception is also thrown for a <a href=../../features/binary_formats/ubjson/ ><abbr title="Universal Binary JSON">UBJSON</abbr></a> array of a type that is encoded by its marker alone (<code>Z</code>, <code>T</code> or <code>F</code>) whose declared count exceeds 1,048,576 (<code>1 &lt;&lt; 20</code>). Such an array has no payload, so its count alone decides how much memory is allocated, and a handful of bytes would otherwise describe billions of values. <a href=../../api/basic_json/to_ubjson/ ><code>to_ubjson</code></a> writes longer arrays of these types without the <code>$</code> type annotation (the <code>#</code> count and one marker per element are kept), so any value it produces can still be read back.</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.408] excessive array size: 8658170730974374167
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.408] syntax error while parsing CBOR size: excessive array size
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.408] syntax error while parsing CBOR size: excessive map size
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.408] syntax error while parsing UBJSON size: excessive array size
</code></pre></div></p> </div> <h3 id=jsonexceptionout_of_range409>json.exception.out_of_range.409<a class=headerlink href=#jsonexceptionout_of_range409 title="Permanent link">&para;</a></h3> <p>Key identifiers to be serialized to <abbr title="Binary JSON">BSON</abbr> cannot contain code point U+0000, since the key is stored as zero-terminated c-string.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>BSON key cannot contain code point U+0000 (at byte 2)
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range410>json.exception.out_of_range.410<a class=headerlink href=#jsonexceptionout_of_range410 title="Permanent link">&para;</a></h3> <p>This exception is thrown when an undefined value is used with <a href=../../api/macros/nlohmann_json_serialize_enum_strict/ ><code>NLOHMANN_JSON_SERIALIZE_ENUM_STRICT</code></a>, or when an array index in a <abbr title="JavaScript Object Notation">JSON</abbr> pointer exceeds the range of <code>size_type</code> (e.g., on 32-bit platforms).</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>enum value out of range
array index 18446744073709551615 exceeds size_type
</code></pre></div> <p>The second message is thrown, for instance, by <code class=highlight><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"[1, 2]"</span><span class=p>).</span><span class=n>at</span><span class=p>(</span><span class=s>"/18446744073709551615"</span><span class=n>_json_pointer</span><span class=p>)</span></code> on a 64-bit platform, where <code>size_type</code> is <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span></code> and this index is <code>SIZE_MAX</code>. An index that does not fit into 64 bits (such as <code>18446744073709551616</code>) is not reported as 410 but as <a href=#jsonexceptionout_of_range404><code>out_of_range.404</code></a>.</p> </div> <h3 id=jsonexceptionout_of_range411>json.exception.out_of_range.411<a class=headerlink href=#jsonexceptionout_of_range411 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch <code>add</code> operation cannot be applied because the target location's parent is neither an object nor an array. Per <a href="https://datatracker.ietf.org/doc/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902</a>, an <code>add</code> target must reference a member of an existing object or an element of an existing array; a primitive value (string, number, boolean, etc.) cannot receive a new member or element.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>cannot add value: the JSON Patch 'add' target's parent is of type string, but must be an object or array
</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 hit an internal assertion (aborting the program in debug builds) or was silently ignored when assertions were disabled.</p> <p>A <code>null</code> parent is rejected as well. Before version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, an <code>add</code> into a <code>null</code> parent silently converted it to an object (e.g., <code>add</code> at <code>/foo/bar</code> turned <code>{"foo":null}</code> into <code>{"foo":{"bar":1}}</code>).</p> </div> <h3 id=jsonexceptionout_of_range412>json.exception.out_of_range.412<a class=headerlink href=#jsonexceptionout_of_range412 title="Permanent link">&para;</a></h3> <p><abbr title="Binary JSON">BSON</abbr> stores the length of documents, arrays, strings, and binary values in a signed 32-bit integer, and MessagePack stores the length of strings, binary values, arrays, and objects in at most an unsigned 32-bit integer. This exception is thrown when a value is too large to be described by such a length field.</p> <div class="admonition failure"> <p class=admonition-title>Example messages</p> <p><div class=highlight><pre><span></span><code>BSON length 2147483661 exceeds maximum of 2147483647
</code></pre></div> <div class=highlight><pre><span></span><code>MessagePack length 4294967296 exceeds maximum of 4294967295
</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>. Before that, the <abbr title="Binary JSON">BSON</abbr> length was silently truncated, and <a href=../../api/basic_json/to_bson/ ><code>to_bson</code></a> produced documents with negative length prefixes that <a href=../../api/basic_json/from_bson/ ><code>from_bson</code></a> rejected; <a href=../../api/basic_json/to_msgpack/ ><code>to_msgpack</code></a> wrote such a value without any length, producing output that could not be read back.</p> </div> <h3 id=jsonexceptionout_of_range413>json.exception.out_of_range.413<a class=headerlink href=#jsonexceptionout_of_range413 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch <code>remove</code> operation cannot be applied because the target location's parent is neither an object nor an array. Per <a href="https://datatracker.ietf.org/doc/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902</a>, a <code>remove</code> target must reference a member of an existing object or an element of an existing array; a primitive value (string, number, boolean, etc.) or <code>null</code> has no members or elements to remove.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array
</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>cannot move value: 'from' path '/0' is a proper prefix of 'path' '/0/0'
</code></pre></div></p> </div> <h3 id=jsonexceptionout_of_range409>json.exception.out_of_range.409<a class=headerlink href=#jsonexceptionout_of_range409 title="Permanent link">&para;</a></h3> <p>Key identifiers to be serialized to <abbr title="Binary JSON">BSON</abbr> cannot contain code point U+0000, since the key is stored as zero-terminated c-string.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.409] BSON key cannot contain code point U+0000 (at byte 2)
</code></pre></div> </div> <h3 id=jsonexceptionout_of_range410>json.exception.out_of_range.410<a class=headerlink href=#jsonexceptionout_of_range410 title="Permanent link">&para;</a></h3> <p>This exception is thrown when an undefined value is used with <a href=../../api/macros/nlohmann_json_serialize_enum_strict/ ><code>NLOHMANN_JSON_SERIALIZE_ENUM_STRICT</code></a>, or when an array index in a <abbr title="JavaScript Object Notation">JSON</abbr> pointer exceeds the range of <code>size_type</code> (e.g., on 32-bit platforms).</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.410] enum value out of range
[json.exception.out_of_range.410] array index 18446744073709551615 exceeds size_type
</code></pre></div> <p>The second message is thrown, for instance, by <code class=highlight><span class=n>json</span><span class=o>::</span><span class=n>parse</span><span class=p>(</span><span class=s>"[1, 2]"</span><span class=p>).</span><span class=n>at</span><span class=p>(</span><span class=s>"/18446744073709551615"</span><span class=n>_json_pointer</span><span class=p>)</span></code> on a 64-bit platform, where <code>size_type</code> is <code class=highlight><span class=n>std</span><span class=o>::</span><span class=kt>size_t</span></code> and this index is <code>SIZE_MAX</code>. An index that does not fit into 64 bits (such as <code>18446744073709551616</code>) is not reported as 410 but as <a href=#jsonexceptionout_of_range404><code>out_of_range.404</code></a>.</p> </div> <h3 id=jsonexceptionout_of_range411>json.exception.out_of_range.411<a class=headerlink href=#jsonexceptionout_of_range411 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch <code>add</code> operation cannot be applied because the target location's parent is neither an object nor an array. Per <a href="https://datatracker.ietf.org/doc/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902</a>, an <code>add</code> target must reference a member of an existing object or an element of an existing array; a primitive value (string, number, boolean, etc.) cannot receive a new member or element.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.411] cannot add value: the JSON Patch 'add' target's parent is of type string, but must be an object or array
</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 hit an internal assertion (aborting the program in debug builds) or was silently ignored when assertions were disabled.</p> <p>A <code>null</code> parent is rejected as well. Before version 3.13.0 <span class=unreleased-version title="Not part of a release yet; the latest release is 3.12.0.">unreleased</span>, an <code>add</code> into a <code>null</code> parent silently converted it to an object (e.g., <code>add</code> at <code>/foo/bar</code> turned <code>{"foo":null}</code> into <code>{"foo":{"bar":1}}</code>).</p> </div> <h3 id=jsonexceptionout_of_range412>json.exception.out_of_range.412<a class=headerlink href=#jsonexceptionout_of_range412 title="Permanent link">&para;</a></h3> <p><abbr title="Binary JSON">BSON</abbr> stores the length of documents, arrays, strings, and binary values in a signed 32-bit integer, and MessagePack stores the length of strings, binary values, arrays, and objects in at most an unsigned 32-bit integer. This exception is thrown when a value is too large to be described by such a length field.</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.412] BSON length 2147483661 exceeds maximum of 2147483647
</code></pre></div> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.412] MessagePack length 4294967296 exceeds maximum of 4294967295
</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>. Before that, the <abbr title="Binary JSON">BSON</abbr> length was silently truncated, and <a href=../../api/basic_json/to_bson/ ><code>to_bson</code></a> produced documents with negative length prefixes that <a href=../../api/basic_json/from_bson/ ><code>from_bson</code></a> rejected; <a href=../../api/basic_json/to_msgpack/ ><code>to_msgpack</code></a> wrote such a value without any length, producing output that could not be read back.</p> </div> <h3 id=jsonexceptionout_of_range413>json.exception.out_of_range.413<a class=headerlink href=#jsonexceptionout_of_range413 title="Permanent link">&para;</a></h3> <p>A <abbr title="JavaScript Object Notation">JSON</abbr> Patch <code>remove</code> operation cannot be applied because the target location's parent is neither an object nor an array. Per <a href="https://datatracker.ietf.org/doc/html/rfc6902"><abbr title="Request for Comments">RFC</abbr> 6902</a>, a <code>remove</code> target must reference a member of an existing object or an element of an existing array; a primitive value (string, number, boolean, etc.) or <code>null</code> has no members or elements to remove.</p> <div class="admonition failure"> <p class=admonition-title>Example message</p> <div class=highlight><pre><span></span><code>[json.exception.out_of_range.413] cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array
</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
@@ -318,4 +306,4 @@ array index 18446744073709551615 exceeds size_type
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> <!-- 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 26, 2026 19:13:30 UTC">October 26, 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> <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 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></svg> </a> <a href="https://www.linkedin.com/in/nielslohmann/" target="_blank" rel="noopener" title="www.linkedin.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 448 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="M416 32H31.9C14.3 32 0 46.5 0 64.3v383.4C0 465.5 14.3 480 31.9 480H416c17.6 0 32-14.5 32-32.3V64.3c0-17.8-14.4-32.3-32-32.3M135.4 416H69V202.2h66.5V416zM102.2 96a38.5 38.5 0 1 1 0 77 38.5 38.5 0 1 1 0-77m282.1 320h-66.4V312c0-24.8-.5-56.7-34.5-56.7-34.6 0-39.9 27-39.9 54.9V416h-66.4V202.2h63.7v29.2h.9c8.9-16.8 30.6-34.5 62.9-34.5 67.2 0 79.7 44.3 79.7 101.9z"/></svg> </a> <a href="https://www.xing.com/profile/Niels_Lohmann" target="_blank" rel="noopener" title="www.xing.com" class="md-social__link"> <svg xmlns=http://www.w3.org/2000/svg viewbox="0 0 384 512"><!-- Font Awesome Free 7.1.0 by @fontawesome - https://fontawesome.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="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
+53 -45
View File
@@ -6,35 +6,31 @@
All exceptions inherit from class `json::exception` (which in turn inherits from `std::exception`). It is used as the base class for all exceptions thrown by the `basic_json` class. This class can hence be used as "wildcard" to catch exceptions.
The map shows the class tree and every exception id documented on this page; click an id to jump to its section.
The exception classes from `std::exception` down to the five families, each with the ids it can throw. Every id chip links to the section that describes it.
Which exception an element access throws depends on the function and on the type of the value:
```
classDiagram
direction LR
class `std::exception` {
<<interface>>
}
class `json::exception` {
+const int id
+const char* what() const
}
class `json::parse_error` {
+const std::size_t byte
}
class `json::invalid_iterator`
class `json::type_error`
class `json::out_of_range`
class `json::other_error`
`std::exception` <|-- `json::exception`
`json::exception` <|-- `json::parse_error`
`json::exception` <|-- `json::invalid_iterator`
`json::exception` <|-- `json::type_error`
`json::exception` <|-- `json::out_of_range`
`json::exception` <|-- `json::other_error`
flowchart LR
S{{"which call?"}} -->|"at(key)"| A{{"j is"}}
A -->|"object, key missing"| A1["out_of_range.403"]
A -->|"array or null"| A2["type_error.304"]
S -->|"at(index)"| B{{"j is"}}
B -->|"array, index >= size()"| B1["out_of_range.401"]
B -->|"object or null"| B2["type_error.304"]
S -->|"non-const operator[](key)"| C{{"j is"}}
C -->|"object or null"| C1["no exception: a missing key is inserted as null"]
C -->|"array"| C2["type_error.305"]
S -->|"value(key, default)"| D{{"j is"}}
D -->|"object, key missing"| D1["no exception: returns the default"]
D -->|"object, incompatible value type"| D2["type_error.302"]
D -->|"array or null"| D3["type_error.306"]
```
Exceptions thrown by element access. Start at the call on the left, follow the edge that matches the type of `j`, and read the exception id (or "no exception") in the box at the end.
### Switch off exceptions
Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol [`JSON_NOEXCEPTION`](https://json.nlohmann.me/api/macros/json_noexception/index.md). In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `throw`), `JSON_TRY_USER` (overriding `try`), and `JSON_CATCH_USER` (overriding `catch`).
@@ -276,7 +272,7 @@ JSON uses the `\uxxxx` format to describe Unicode characters. Code points above
Example message
```
parse error at 14: missing or wrong low surrogate
[json.exception.parse_error.102] parse error at 14: missing or wrong low surrogate
```
Note
@@ -290,7 +286,7 @@ Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are inva
Example message
```
parse error: code points above 0x10FFFF are invalid
[json.exception.parse_error.103] parse error: code points above 0x10FFFF are invalid
```
Note
@@ -1045,7 +1041,7 @@ The provided array index `i` is larger than `size-1`.
Example message
```
array index 3 is out of range
[json.exception.out_of_range.401] array index 3 is out of range
```
### json.exception.out_of_range.402
@@ -1055,7 +1051,7 @@ The special array index `-` in a JSON Pointer never describes a valid element of
Example message
```
array index '-' (3) is out of range
[json.exception.out_of_range.402] array index '-' (3) is out of range
```
### json.exception.out_of_range.403
@@ -1065,7 +1061,7 @@ The provided key was not found in the JSON object.
Example message
```
key 'foo' not found
[json.exception.out_of_range.403] key 'foo' not found
```
### json.exception.out_of_range.404
@@ -1075,7 +1071,7 @@ A reference token in a JSON Pointer could not be resolved, for instance an array
Example message
```
unresolved reference token 'foo'
[json.exception.out_of_range.404] unresolved reference token 'foo'
```
### json.exception.out_of_range.405
@@ -1085,7 +1081,7 @@ The JSON Patch operations 'remove' and 'move' cannot be applied to the root elem
Example message
```
JSON pointer has no parent
[json.exception.out_of_range.405] JSON pointer has no parent
```
### json.exception.out_of_range.406
@@ -1095,7 +1091,7 @@ A parsed number could not be stored without changing it to NaN or INF. For the b
Example messages
```
number overflow parsing '10E1000'
[json.exception.out_of_range.406] number overflow parsing '10E1000'
```
```
@@ -1123,11 +1119,11 @@ Before version 3.13.0 unreleased, CBOR, MessagePack, and BSON silently truncated
Example messages
```
integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
[json.exception.out_of_range.407] integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
```
```
integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
[json.exception.out_of_range.407] integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
```
### json.exception.out_of_range.408
@@ -1139,7 +1135,7 @@ The exception is also thrown for a [UBJSON](https://json.nlohmann.me/features/bi
Example messages
```
excessive array size: 8658170730974374167
[json.exception.out_of_range.408] excessive array size: 8658170730974374167
```
```
@@ -1161,7 +1157,7 @@ Key identifiers to be serialized to BSON cannot contain code point U+0000, since
Example message
```
BSON key cannot contain code point U+0000 (at byte 2)
[json.exception.out_of_range.409] BSON key cannot contain code point U+0000 (at byte 2)
```
### json.exception.out_of_range.410
@@ -1171,8 +1167,8 @@ This exception is thrown when an undefined value is used with [`NLOHMANN_JSON_SE
Example message
```
enum value out of range
array index 18446744073709551615 exceeds size_type
[json.exception.out_of_range.410] enum value out of range
[json.exception.out_of_range.410] array index 18446744073709551615 exceeds size_type
```
The second message is thrown, for instance, by `json::parse("[1, 2]").at("/18446744073709551615"_json_pointer)` on a 64-bit platform, where `size_type` is `std::size_t` and this index is `SIZE_MAX`. An index that does not fit into 64 bits (such as `18446744073709551616`) is not reported as 410 but as [`out_of_range.404`](#jsonexceptionout_of_range404).
@@ -1184,7 +1180,7 @@ A JSON Patch `add` operation cannot be applied because the target location's par
Example message
```
cannot add value: the JSON Patch 'add' target's parent is of type string, but must be an object or array
[json.exception.out_of_range.411] cannot add value: the JSON Patch 'add' target's parent is of type string, but must be an object or array
```
Note
@@ -1200,11 +1196,11 @@ BSON stores the length of documents, arrays, strings, and binary values in a sig
Example messages
```
BSON length 2147483661 exceeds maximum of 2147483647
[json.exception.out_of_range.412] BSON length 2147483661 exceeds maximum of 2147483647
```
```
MessagePack length 4294967296 exceeds maximum of 4294967295
[json.exception.out_of_range.412] MessagePack length 4294967296 exceeds maximum of 4294967295
```
Note
@@ -1218,7 +1214,7 @@ A JSON Patch `remove` operation cannot be applied because the target location's
Example message
```
cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array
[json.exception.out_of_range.413] cannot remove value: the JSON Patch 'remove' target's parent is of type number, but must be an object or array
```
Note
@@ -1232,7 +1228,7 @@ A JSON Patch `move` operation's `"from"` location is a proper prefix of its `"pa
Example message
```
cannot move value: 'from' path '/0' is a proper prefix of 'path' '/0/0'
[json.exception.out_of_range.414] cannot move value: 'from' path '/0' is a proper prefix of 'path' '/0/0'
```
Note
@@ -1354,3 +1350,15 @@ Example message
Note
This exception was added in version 3.13.0 unreleased. Before that, debug builds aborted on an assertion and release builds wrote a `$` marker without `#`, which [`from_ubjson`](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md) then rejected.
## See also
- [`exception`](https://json.nlohmann.me/api/basic_json/exception/index.md) - base class of all exceptions thrown by the library
- [`parse_error`](https://json.nlohmann.me/api/basic_json/parse_error/index.md) - exceptions indicating a parse error
- [`invalid_iterator`](https://json.nlohmann.me/api/basic_json/invalid_iterator/index.md) - exceptions indicating errors with iterators
- [`type_error`](https://json.nlohmann.me/api/basic_json/type_error/index.md) - exceptions indicating a wrong type
- [`out_of_range`](https://json.nlohmann.me/api/basic_json/out_of_range/index.md) - exceptions indicating access out of range
- [`other_error`](https://json.nlohmann.me/api/basic_json/other_error/index.md) - exceptions indicating other library errors
- [`JSON_NOEXCEPTION`](https://json.nlohmann.me/api/macros/json_noexception/index.md) - switch off exceptions
- [`JSON_DIAGNOSTICS`](https://json.nlohmann.me/api/macros/json_diagnostics/index.md) - extended exception messages with the path of the failing value
- [Working Without Exceptions](https://json.nlohmann.me/features/no_exceptions/index.md) - use the library without exceptions