</code></pre></div></details><p>Note the explanatory <ahref=https://en.cppreference.com/w/cpp/error/exception/what><code>what()</code></a> string of exceptions is not available for MSVC if exceptions are disabled, see <ahref=https://github.com/nlohmann/json/discussions/2824>#2824</a>.</p><p>See <ahref=../../api/macros/json_throw_user/>documentation of <code>JSON_TRY_USER</code>, <code>JSON_CATCH_USER</code> and <code>JSON_THROW_USER</code></a> for more information.</p><h3id=extended-diagnostic-messages>Extended diagnostic messages<aclass=headerlinkhref=#extended-diagnostic-messagestitle="Permanent link">¶</a></h3><p>Exceptions in the library are thrown in the local context of the JSON value they are detected. This makes detailed diagnostics messages, and hence debugging, difficult.</p><detailsclass=example><summary>Example</summary><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
</code></pre></div><p>Output:</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.302] type must be number, but is string
</code></pre></div><p>This exception can be hard to debug if storing the value <codeclass=highlight><spanclass=s>"12"</span><spanclass=w></span></code> and accessing it is further apart.</p></details><p>To create better diagnostics messages, each JSON value needs a pointer to its parent value such that a global context (i.e., a path from the root value to the value that lead to the exception) can be created. That global context is provided as <ahref=../../features/json_pointer/>JSON Pointer</a>.</p><p>As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol <ahref=../../api/macros/json_diagnostics/><code>JSON_DIAGNOSTICS</code></a> to <code>1</code> before including <code>json.hpp</code>.</p><detailsclass=example><summary>Example</summary><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
</code></pre></div><p>Output:</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.302] (/address/housenumber) type must be number, but is string
</code></pre></div><p>Now the exception message contains a JSON Pointer <code>/address/housenumber</code> that indicates which value has the wrong type.</p></details><p>See <ahref=../../api/macros/json_diagnostics/>documentation of <code>JSON_DIAGNOSTICS</code></a> for more information.</p><h2id=parse-errors>Parse errors<aclass=headerlinkhref=#parse-errorstitle="Permanent link">¶</a></h2><p>This exception is thrown by the library when a parse error occurs. Parse errors can occur during the deserialization of JSON text, CBOR, MessagePack, as well as when using JSON Patch.</p><p>Exceptions have ids 1xx.</p><divclass="admonition info"><pclass=admonition-title>Byte index</p><p>Member <code>byte</code> holds the byte index of the last read character in the input file.</p><p>For an input with n bytes, 1 is the index of the first character and n+1 is the index of the terminating null byte or the end of file. This also holds true when reading a byte vector (CBOR or MessagePack).</p></div><detailsclass=example><summary>Example</summary><p>The following code shows how a <code>parse_error</code> exception can be caught.</p><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
<spanclass=w></span><spanclass=o><<</span><spanclass=w></span><spanclass=s>"byte position of error: "</span><spanclass=w></span><spanclass=o><<</span><spanclass=w></span><spanclass=n>e</span><spanclass=p>.</span><spanclass=n>byte</span><spanclass=w></span><spanclass=o><<</span><spanclass=w></span><spanclass=n>std</span><spanclass=o>::</span><spanclass=n>endl</span><spanclass=p>;</span><spanclass=w></span>
</code></pre></div><p>Output:</p><divclass=highlight><pre><span></span><code>message: [json.exception.parse_error.101] parse error at line 1, column 8: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
exception id: 101
byte position of error: 8
</code></pre></div></details><h3id=jsonexceptionparse_error101>json.exception.parse_error.101<aclass=headerlinkhref=#jsonexceptionparse_error101title="Permanent link">¶</a></h3><p>This error indicates a syntax error while deserializing a JSON text. The error message describes that an unexpected token (character) was encountered, and the member <code>byte</code> indicates the error position.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><p>Input ended prematurely:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at 2: unexpected end of input; expected string literal
</code></pre></div><p>No input:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 1, column 1: syntax error while parsing value - unexpected end of input; expected '[', '{', or a literal
</code></pre></div><p>Control character was not escaped:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 1, column 2: syntax error while parsing value - invalid string: control character U+0009 (HT) must be escaped to \u0009 or \\; last read: '"<U+0009>'"
</code></pre></div><p>String was not closed:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 1, column 2: syntax error while parsing value - invalid string: missing closing quote; last read: '"'
</code></pre></div><p>Invalid number format:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 1, column 3: syntax error while parsing value - invalid number; expected '+', '-', or digit after exponent; last read: '1E'
</code></pre></div><p><code>\u</code> was not be followed by four hex digits:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 1, column 6: syntax error while parsing value - invalid string: '\u' must be followed by 4 hex digits; last read: '"\u01"'
</code></pre></div><p>Invalid UTF-8 surrogate pair:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 1, column 13: syntax error while parsing value - invalid string: surrogate U+DC00..U+DFFF must follow U+D800..U+DBFF; last read: '"\uD7FF\uDC00'"
</code></pre></div><p>Invalid UTF-8 byte:</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.101] parse error at line 3, column 24: syntax error while parsing value - invalid string: ill-formed UTF-8 byte; last read: '"vous \352t'
</code></pre></div></div><divclass="admonition tip"><pclass=admonition-title>Tip</p><ul><li>Make sure the input is correctly read. Try to write the input to standard output to check if, for instance, the input file was successfully opened.</li><li>Paste the input to a JSON validator like <ahref=http://jsonlint.com>http://jsonlint.com</a> or a tool like <ahref=https://stedolan.github.io/jq/>jq</a>.</li></ul></div><h3id=jsonexceptionparse_error102>json.exception.parse_error.102<aclass=headerlinkhref=#jsonexceptionparse_error102title="Permanent link">¶</a></h3><p>JSON 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><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>parse error at 14: missing or wrong low surrogate
</code></pre></div></div><divclass="admonition note"><pclass=admonition-title>Note</p><p>This exception is not used any more. Instead <ahref=#jsonexceptionparse_error101>json.exception.parse_error.101</a> with a more detailed description is used.</p></div><h3id=jsonexceptionparse_error103>json.exception.parse_error.103<aclass=headerlinkhref=#jsonexceptionparse_error103title="Permanent link">¶</a></h3><p>Unicode supports code points up to 0x10FFFF. Code points above 0x10FFFF are invalid.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>parse error: code points above 0x10FFFF are invalid
</code></pre></div></div><divclass="admonition note"><pclass=admonition-title>Note</p><p>This exception is not used any more. Instead <ahref=#jsonexceptionparse_error101>json.exception.parse_error.101</a> with a more detailed description is used.</p></div><h3id=jsonexceptionparse_error104>json.exception.parse_error.104<aclass=headerlinkhref=#jsonexceptionparse_error104title="Permanent link">¶</a></h3><p><ahref=https://tools.ietf.org/html/rfc6902>RFC 6902</a> requires a JSON Patch document to be a JSON document that represents an array of objects.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.104] parse error: JSON patch must be an array of objects
</code></pre></div></div><h3id=jsonexceptionparse_error105>json.exception.parse_error.105<aclass=headerlinkhref=#jsonexceptionparse_error105title="Permanent link">¶</a></h3><p>An operation of a JSON 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><divclass="admonition failure"><pclass=admonition-title>Example message</p><p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.105] parse error: operation 'add' must have member 'value'
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.105] parse error: operation 'copy' must have string member 'from'
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.105] parse error: operation value 'foo' is invalid
</code></pre></div></p></div><h3id=jsonexceptionparse_error106>json.exception.parse_error.106<aclass=headerlinkhref=#jsonexceptionparse_error106title="Permanent link">¶</a></h3><p>An array index in a JSON Pointer (<ahref=https://tools.ietf.org/html/rfc6901>RFC 6901</a>) may be <code>0</code> or any number without a leading <code>0</code>.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'
</code></pre></div></div><h3id=jsonexceptionparse_error107>json.exception.parse_error.107<aclass=headerlinkhref=#jsonexceptionparse_error107title="Permanent link">¶</a></h3><p>A JSON Pointer must be a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a <code>/</code> character.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.107] parse error at byte 1: JSON pointer must be empty or begin with '/' - was: 'foo'
</code></pre></div></div><h3id=jsonexceptionparse_error108>json.exception.parse_error.108<aclass=headerlinkhref=#jsonexceptionparse_error108title="Permanent link">¶</a></h3><p>In a JSON Pointer, only <code>~0</code> and <code>~1</code> are valid escape sequences.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.108] parse error: escape character '~' must be followed with '0' or '1'
</code></pre></div></div><h3id=jsonexceptionparse_error109>json.exception.parse_error.109<aclass=headerlinkhref=#jsonexceptionparse_error109title="Permanent link">¶</a></h3><p>A JSON Pointer array index must be a number.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.109] parse error: array index 'one' is not a number
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.109] parse error: array index '+1' is not a number
</code></pre></div></p></div><h3id=jsonexceptionparse_error110>json.exception.parse_error.110<aclass=headerlinkhref=#jsonexceptionparse_error110title="Permanent link">¶</a></h3><p>When parsing CBOR or MessagePack, the byte vector ends before the complete value has been read.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.110] parse error at byte 5: syntax error while parsing CBOR string: unexpected end of input
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.110] parse error at byte 2: syntax error while parsing UBJSON value: expected end of input; last byte: 0x5A
</code></pre></div></p></div><h3id=jsonexceptionparse_error112>json.exception.parse_error.112<aclass=headerlinkhref=#jsonexceptionparse_error112title="Permanent link">¶</a></h3><p>An unexpected byte was read in a <ahref=../../features/binary_formats/>binary format</a> or length information is invalid (<ahref=../../features/binary_formats/bson/>BSON</a>).</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0x1C
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing MessagePack value: invalid byte: 0xC1
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.112] parse error at byte 4: syntax error while parsing BJData size: expected '#' after type information; last byte: 0x02
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.112] parse error at byte 4: syntax error while parsing UBJSON size: expected '#' after type information; last byte: 0x02
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.112] parse error at byte 10: syntax error while parsing BSON string: string length must be at least 1, is -2147483648
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.112] parse error at byte 15: syntax error while parsing BSON binary: byte array length cannot be negative, is -1
</code></pre></div></p></div><h3id=jsonexceptionparse_error113>json.exception.parse_error.113<aclass=headerlinkhref=#jsonexceptionparse_error113title="Permanent link">¶</a></h3><p>While parsing a map key, a value that is not a string has been read.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing CBOR string: expected length specification (0x60-0x7B) or indefinite string type (0x7F); last byte: 0xFF
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing MessagePack string: expected length specification (0xA0-0xBF, 0xD9-0xDB); last byte: 0xFF
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.parse_error.113] parse error at byte 2: syntax error while parsing UBJSON char: byte after 'C' must be in range 0x00..0x7F; last byte: 0x82
</code></pre></div></p></div><h3id=jsonexceptionparse_error114>json.exception.parse_error.114<aclass=headerlinkhref=#jsonexceptionparse_error114title="Permanent link">¶</a></h3><p>The parsing of the corresponding BSON record type is not implemented (yet).</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.parse_error.114] parse error at byte 5: Unsupported BSON record type 0xFF
</code></pre></div></div><h3id=jsonexceptionparse_error115>json.exception.parse_error.115<aclass=headerlinkhref=#jsonexceptionparse_error115title="Permanent link">¶</a></h3><p>A UBJSON high-precision number could not be parsed.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=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><h2id=iterator-errors>Iterator errors<aclass=headerlinkhref=#iterator-errorstitle="Permanent link">¶</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><detailsclass=example><summary>Example</summary><p>The following code shows how an <code>invalid_iterator</code> exception can be caught.</p><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
</code></pre></div><p>Output:</p><divclass=highlight><pre><span></span><code>message: [json.exception.invalid_iterator.207] cannot use key() for non-object iterators
exception id: 207
</code></pre></div></details><h3id=jsonexceptioninvalid_iterator201>json.exception.invalid_iterator.201<aclass=headerlinkhref=#jsonexceptioninvalid_iterator201title="Permanent link">¶</a></h3><p>The iterators passed to constructor <code>basic_json(InputIT first, InputIT last)</code> are not compatible, meaning they do not belong to the same container. Therefore, the range (<code>first</code>, <code>last</code>) is invalid.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.201] iterators are not compatible
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator202>json.exception.invalid_iterator.202<aclass=headerlinkhref=#jsonexceptioninvalid_iterator202title="Permanent link">¶</a></h3><p>In the <ahref=../../api/basic_json/erase/>erase</a> or insert function, the passed iterator <code>pos</code> does not belong to the JSON value for which the function was called. It hence does not define a valid position for the deletion/insertion.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.202] iterator does not fit current value
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.202] iterators first and last must point to objects
</code></pre></div></p></div><h3id=jsonexceptioninvalid_iterator203>json.exception.invalid_iterator.203<aclass=headerlinkhref=#jsonexceptioninvalid_iterator203title="Permanent link">¶</a></h3><p>Either iterator passed to function <ahref=../../api/basic_json/erase/><code>erase(IteratorType first, IteratorType last</code>)</a> does not belong to the JSON value from which values shall be erased. It hence does not define a valid range to delete values from.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.203] iterators do not fit current value
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator204>json.exception.invalid_iterator.204<aclass=headerlinkhref=#jsonexceptioninvalid_iterator204title="Permanent link">¶</a></h3><p>When an iterator range for a primitive type (number, boolean, or string) is passed to a constructor or an <ahref=../../api/basic_json/erase/>erase</a> function, this range has to be exactly (<code>begin(),</code><code>end()),</code> because this is the only way the single stored value is expressed. All other ranges are invalid.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.204] iterators out of range
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator205>json.exception.invalid_iterator.205<aclass=headerlinkhref=#jsonexceptioninvalid_iterator205title="Permanent link">¶</a></h3><p>When an iterator for a primitive type (number, boolean, or string) is passed to an <ahref=../../api/basic_json/erase/>erase</a> function, the iterator has to be the <code>begin()</code> iterator, because it is the only way to address the stored value. All other iterators are invalid.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.205] iterator out of range
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator206>json.exception.invalid_iterator.206<aclass=headerlinkhref=#jsonexceptioninvalid_iterator206title="Permanent link">¶</a></h3><p>The iterators passed to constructor <code>basic_json(InputIT first, InputIT last)</code> belong to a JSON null value and hence to not define a valid range.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.206] cannot construct with iterators from null
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator207>json.exception.invalid_iterator.207<aclass=headerlinkhref=#jsonexceptioninvalid_iterator207title="Permanent link">¶</a></h3><p>The <code>key()</code> member function can only be used on iterators belonging to a JSON object, because other types do not have a concept of a key.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.207] cannot use key() for non-object iterators
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator208>json.exception.invalid_iterator.208<aclass=headerlinkhref=#jsonexceptioninvalid_iterator208title="Permanent link">¶</a></h3><p>The <code>operator[]</code> to specify a concrete offset cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.208] cannot use operator[] for object iterators
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator209>json.exception.invalid_iterator.209<aclass=headerlinkhref=#jsonexceptioninvalid_iterator209title="Permanent link">¶</a></h3><p>The offset operators (<code>+</code>, <code>-</code>, <code>+=</code>, <code>-=</code>) cannot be used on iterators belonging to a JSON object, because JSON objects are unordered.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.209] cannot use offsets with object iterators
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator210>json.exception.invalid_iterator.210<aclass=headerlinkhref=#jsonexceptioninvalid_iterator210title="Permanent link">¶</a></h3><p>The iterator range passed to the insert function are not compatible, meaning they do not belong to the same container. Therefore, the range (<code>first</code>, <code>last</code>) is invalid.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.210] iterators do not fit
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator211>json.exception.invalid_iterator.211<aclass=headerlinkhref=#jsonexceptioninvalid_iterator211title="Permanent link">¶</a></h3><p>The iterator range passed to the insert function must not be a subrange of the container to insert to.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.211] passed iterators may not belong to container
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator212>json.exception.invalid_iterator.212<aclass=headerlinkhref=#jsonexceptioninvalid_iterator212title="Permanent link">¶</a></h3><p>When two iterators are compared, they must belong to the same container.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.212] cannot compare iterators of different containers
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator213>json.exception.invalid_iterator.213<aclass=headerlinkhref=#jsonexceptioninvalid_iterator213title="Permanent link">¶</a></h3><p>The order of object iterators cannot be compared, because JSON objects are unordered.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.213] cannot compare order of object iterators
</code></pre></div></div><h3id=jsonexceptioninvalid_iterator214>json.exception.invalid_iterator.214<aclass=headerlinkhref=#jsonexceptioninvalid_iterator214title="Permanent link">¶</a></h3><p>Cannot get value for iterator: Either the iterator belongs to a null value or it is an iterator to a primitive type (number, boolean, or string), but the iterator is different to <code>begin()</code>.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.invalid_iterator.214] cannot get value
</code></pre></div></div><h2id=type-errors>Type errors<aclass=headerlinkhref=#type-errorstitle="Permanent link">¶</a></h2><p>This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type does not match the expected semantics.</p><p>Exceptions have ids 3xx.</p><detailsclass=example><summary>Example</summary><p>The following code shows how a <code>type_error</code> exception can be caught.</p><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
</code></pre></div><p>Output:</p><divclass=highlight><pre><span></span><code>message: [json.exception.type_error.308] cannot use push_back() with string
exception id: 308
</code></pre></div></details><h3id=jsonexceptiontype_error301>json.exception.type_error.301<aclass=headerlinkhref=#jsonexceptiontype_error301title="Permanent link">¶</a></h3><p>To create an object from an initializer list, the initializer list must consist only of a list of pairs whose first element is a string. When this constraint is violated, an array is created instead.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.301] cannot create object from initializer list
</code></pre></div></div><h3id=jsonexceptiontype_error302>json.exception.type_error.302<aclass=headerlinkhref=#jsonexceptiontype_error302title="Permanent link">¶</a></h3><p>During implicit or explicit value conversion, the JSON type must be compatible to the target type. For instance, a JSON string can only be converted into string types, but not into numbers or boolean types.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.type_error.302] type must be object, but is null
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.type_error.302] type must be string, but is object
</code></pre></div></p></div><h3id=jsonexceptiontype_error303>json.exception.type_error.303<aclass=headerlinkhref=#jsonexceptiontype_error303title="Permanent link">¶</a></h3><p>To retrieve a reference to a value stored in a <code>basic_json</code> object with <code>get_ref</code>, the type of the reference must match the value type. For instance, for a JSON array, the <code>ReferenceType</code> must be <code>array_t &</code>.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is object
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.type_error.303] incompatible ReferenceType for get_ref, actual type is number"
</code></pre></div></p></div><h3id=jsonexceptiontype_error304>json.exception.type_error.304<aclass=headerlinkhref=#jsonexceptiontype_error304title="Permanent link">¶</a></h3><p>The <code>at()</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.type_error.304] cannot use at() with string
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.type_error.304] cannot use at() with number
</code></pre></div></p></div><h3id=jsonexceptiontype_error305>json.exception.type_error.305<aclass=headerlinkhref=#jsonexceptiontype_error305title="Permanent link">¶</a></h3><p>The <code>operator[]</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.type_error.305] cannot use operator[] with a string argument with array
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.type_error.305] cannot use operator[] with a numeric argument with object
</code></pre></div></p></div><h3id=jsonexceptiontype_error306>json.exception.type_error.306<aclass=headerlinkhref=#jsonexceptiontype_error306title="Permanent link">¶</a></h3><p>The <code>value()</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.306] cannot use value() with number
</code></pre></div></div><h3id=jsonexceptiontype_error307>json.exception.type_error.307<aclass=headerlinkhref=#jsonexceptiontype_error307title="Permanent link">¶</a></h3><p>The <ahref=../../api/basic_json/erase/><code>erase()</code></a> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.307] cannot use erase() with string
</code></pre></div></div><h3id=jsonexceptiontype_error308>json.exception.type_error.308<aclass=headerlinkhref=#jsonexceptiontype_error308title="Permanent link">¶</a></h3><p>The <code>push_back()</code> and <code>operator+=</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.308] cannot use push_back() with string
</code></pre></div></div><h3id=jsonexceptiontype_error309>json.exception.type_error.309<aclass=headerlinkhref=#jsonexceptiontype_error309title="Permanent link">¶</a></h3><p>The <code>insert()</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.type_error.309] cannot use insert() with array
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.type_error.309] cannot use insert() with number
</code></pre></div></p></div><h3id=jsonexceptiontype_error310>json.exception.type_error.310<aclass=headerlinkhref=#jsonexceptiontype_error310title="Permanent link">¶</a></h3><p>The <code>swap()</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.310] cannot use swap() with number
</code></pre></div></div><h3id=jsonexceptiontype_error311>json.exception.type_error.311<aclass=headerlinkhref=#jsonexceptiontype_error311title="Permanent link">¶</a></h3><p>The <code>emplace()</code> and <code>emplace_back()</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p><divclass=highlight><pre><span></span><code>[json.exception.type_error.311] cannot use emplace() with number
</code></pre></div><divclass=highlight><pre><span></span><code>[json.exception.type_error.311] cannot use emplace_back() with number
</code></pre></div></p></div><h3id=jsonexceptiontype_error312>json.exception.type_error.312<aclass=headerlinkhref=#jsonexceptiontype_error312title="Permanent link">¶</a></h3><p>The <code>update()</code> member functions can only be executed for certain JSON types.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.312] cannot use update() with array
</code></pre></div></div><h3id=jsonexceptiontype_error313>json.exception.type_error.313<aclass=headerlinkhref=#jsonexceptiontype_error313title="Permanent link">¶</a></h3><p>The <code>unflatten</code> function converts an object whose keys are JSON Pointers back into an arbitrary nested JSON value. The JSON Pointers must not overlap, because then the resulting value would not be well-defined.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.313] invalid value to unflatten
</code></pre></div></div><h3id=jsonexceptiontype_error314>json.exception.type_error.314<aclass=headerlinkhref=#jsonexceptiontype_error314title="Permanent link">¶</a></h3><p>The <code>unflatten</code> function only works for an object whose keys are JSON Pointers.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><p>Calling <code>unflatten()</code> on an array <codeclass=highlight><spanclass=p>[</span><spanclass=mi>1</span><spanclass=p>,</span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=mi>3</span><spanclass=p>]</span><spanclass=w></span></code>:</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.314] only objects can be unflattened
</code></pre></div></div><h3id=jsonexceptiontype_error315>json.exception.type_error.315<aclass=headerlinkhref=#jsonexceptiontype_error315title="Permanent link">¶</a></h3><p>The <code>unflatten()</code> function only works for an object whose keys are JSON Pointers and whose values are primitive.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><p>Calling <code>unflatten()</code> on an object <codeclass=highlight><spanclass=p>{</span><spanclass=s2>"/1"</span><spanclass=p>,</span><spanclass=w></span><spanclass=p>[</span><spanclass=mi>1</span><spanclass=p>,</span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=mi>3</span><spanclass=p>]}</span><spanclass=w></span></code>:</p><divclass=highlight><pre><span></span><code>[json.exception.type_error.315] values in object must be primitive
</code></pre></div></div><h3id=jsonexceptiontype_error316>json.exception.type_error.316<aclass=headerlinkhref=#jsonexceptiontype_error316title="Permanent link">¶</a></h3><p>The <code>dump()</code> function only works with UTF-8 encoded strings; that is, if you assign a <code>std::string</code> to a JSON value, make sure it is UTF-8 encoded.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><p>Calling <code>dump()</code> on a JSON value containing an ISO 8859-1 encoded string: <divclass=highlight><pre><span></span><code>[json.exception.type_error.316] invalid UTF-8 byte at index 15: 0x6F
</code></pre></div></p></div><divclass="admonition tip"><pclass=admonition-title>Tip</p><ul><li>Store the source file with UTF-8 encoding.</li><li>Pass an error handler as last parameter to the <code>dump()</code> function to avoid this exception:<ul><li><code>json::error_handler_t::replace</code> will replace invalid bytes sequences with <code>U+FFFD</code></li><li><code>json::error_handler_t::ignore</code> will silently ignore invalid byte sequences</li></ul></li></ul></div><h3id=jsonexceptiontype_error317>json.exception.type_error.317<aclass=headerlinkhref=#jsonexceptiontype_error317title="Permanent link">¶</a></h3><p>The dynamic type of the object cannot be represented in the requested serialization format (e.g. a raw <code>true</code> or <code>null</code> JSON object cannot be serialized to BSON)</p><divclass="admonition failure"><pclass=admonition-title>Example messages</p><p>Serializing <codeclass=highlight><spanclass=kc>null</span><spanclass=w></span></code> to BSON: <divclass=highlight><pre><span></span><code>[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is null
</code></pre></div> Serializing <codeclass=highlight><spanclass=p>[</span><spanclass=mi>1</span><spanclass=p>,</span><spanclass=mi>2</span><spanclass=p>,</span><spanclass=mi>3</span><spanclass=p>]</span><spanclass=w></span></code> to BSON: <divclass=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><divclass="admonition tip"><pclass=admonition-title>Tip</p><p>Encapsulate the JSON value in an object. That is, instead of serializing <codeclass=highlight><spanclass=kc>true</span><spanclass=w></span></code>, serialize <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"value"</span><spanclass=p>:</span><spanclass=w></span><spanclass=kc>true</span><spanclass=p>}</span><spanclass=w></span></code></p></div><h2id=out-of-range>Out of range<aclass=headerlinkhref=#out-of-rangetitle="Permanent link">¶</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 case of array indices or nonexisting object keys.</p><p>Exceptions have ids 4xx.</p><detailsclass=example><summary>Example</summary><p>The following code shows how an <code>out_of_range</code> exception can be caught.</p><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
</code></pre></div><p>Output:</p><divclass=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><h3id=jsonexceptionout_of_range401>json.exception.out_of_range.401<aclass=headerlinkhref=#jsonexceptionout_of_range401title="Permanent link">¶</a></h3><p>The provided array index <code>i</code> is larger than <code>size-1</code>.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>array index 3 is out of range
</code></pre></div></div><h3id=jsonexceptionout_of_range402>json.exception.out_of_range.402<aclass=headerlinkhref=#jsonexceptionout_of_range402title="Permanent link">¶</a></h3><p>The special array index <code>-</code> in a JSON 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><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>array index '-' (3) is out of range
</code></pre></div></div><h3id=jsonexceptionout_of_range403>json.exception.out_of_range.403<aclass=headerlinkhref=#jsonexceptionout_of_range403title="Permanent link">¶</a></h3><p>The provided key was not found in the JSON object.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>key 'foo' not found
</code></pre></div></div><h3id=jsonexceptionout_of_range404>json.exception.out_of_range.404<aclass=headerlinkhref=#jsonexceptionout_of_range404title="Permanent link">¶</a></h3><p>A reference token in a JSON Pointer could not be resolved.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>unresolved reference token 'foo'
</code></pre></div></div><h3id=jsonexceptionout_of_range405>json.exception.out_of_range.405<aclass=headerlinkhref=#jsonexceptionout_of_range405title="Permanent link">¶</a></h3><p>The JSON Patch operations 'remove' and 'add' can not be applied to the root element of the JSON value.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>JSON pointer has no parent
</code></pre></div></div><h3id=jsonexceptionout_of_range406>json.exception.out_of_range.406<aclass=headerlinkhref=#jsonexceptionout_of_range406title="Permanent link">¶</a></h3><p>A parsed number could not be stored as without changing it to NaN or INF.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>number overflow parsing '10E1000'
</code></pre></div></div><h3id=jsonexceptionout_of_range407>json.exception.out_of_range.407<aclass=headerlinkhref=#jsonexceptionout_of_range407title="Permanent link">¶</a></h3><p>UBJSON and BSON only support integer numbers up to 9223372036854775807.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>number overflow serializing '9223372036854775808'
</code></pre></div></div><divclass="admonition note"><pclass=admonition-title>Note</p><p>Since version 3.9.0, integer numbers beyond int64 are serialized as high-precision UBJSON numbers, and this exception does not further occur. </p></div><h3id=jsonexceptionout_of_range408>json.exception.out_of_range.408<aclass=headerlinkhref=#jsonexceptionout_of_range408title="Permanent link">¶</a></h3><p>The size (following <code>#</code>) of an UBJSON array or object exceeds the maximal capacity.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>excessive array size: 8658170730974374167
</code></pre></div></div><h3id=jsonexceptionout_of_range409>json.exception.out_of_range.409<aclass=headerlinkhref=#jsonexceptionout_of_range409title="Permanent link">¶</a></h3><p>Key identifiers to be serialized to BSON cannot contain code point U+0000, since the key is stored as zero-terminated c-string.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><divclass=highlight><pre><span></span><code>BSON key cannot contain code point U+0000 (at byte 2)
</code></pre></div></div><h2id=further-exceptions>Further exceptions<aclass=headerlinkhref=#further-exceptionstitle="Permanent link">¶</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><detailsclass=example><summary>Example</summary><p>The following code shows how an <code>other_error</code> exception can be caught.</p><divclass=highlight><pre><span></span><code><spanclass=cp>#include</span><spanclass=w></span><spanclass=cpf><iostream></span><spanclass=cp></span>
</code></pre></div></details><h3id=jsonexceptionother_error501>json.exception.other_error.501<aclass=headerlinkhref=#jsonexceptionother_error501title="Permanent link">¶</a></h3><p>A JSON Patch operation 'test' failed. The unsuccessful operation is also printed.</p><divclass="admonition failure"><pclass=admonition-title>Example message</p><p>Executing <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"op"</span><spanclass=p>:</span><spanclass=s2>"test"</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"path"</span><spanclass=p>:</span><spanclass=s2>"/baz"</span><spanclass=p>,</span><spanclass=w></span><spanclass=nt>"value"</span><spanclass=p>:</span><spanclass=s2>"bar"</span><spanclass=p>}</span><spanclass=w></span></code> on <codeclass=highlight><spanclass=p>{</span><spanclass=nt>"baz"</span><spanclass=p>:</span><spanclass=w></span><spanclass=s2>"qux"</span><spanclass=p>}</span><spanclass=w></span></code>:</p><divclass=highlight><pre><span></span><code>[json.exception.other_error.501] unsuccessful: {"op":"test","path":"/baz","value":"bar"}
