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.
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`. In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`).
Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
## Parse errors
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.
Exceptions have ids 1xx.
!!! info "Byte index"
Member `byte` holds the byte index of the last read character in the input
file.
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).
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 `byte` indicates the error position.
[json.exception.parse_error.101] parse error at 2: unexpected end of input; expected string literal
```
No input:
```
[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
```
Control character was not escaped:
```
[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>'"
```
String was not closed:
```
[json.exception.parse_error.101] parse error at line 1, column 2: syntax error while parsing value - invalid string: missing closing quote; last read: '"'
```
Invalid number format:
```
[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'
```
`\u` was not be followed by four hex digits:
```
[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"'
```
Invalid UTF-8 surrogate pair:
```
[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'"
```
Invalid UTF-8 byte:
```
[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'
```
!!! tip
- 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 openened.
- Paste the input to a JSON validator like <http://jsonlint.com> or a tool like [jq](https://stedolan.github.io/jq/).
### json.exception.parse_error.102
JSON uses the `\uxxxx` format to describe Unicode characters. Code points above above 0xFFFF are split into two `\uxxxx` entries ("surrogate pairs"). This error indicates that the surrogate pair is incomplete or contains an invalid code point.
[json.exception.parse_error.104] parse error: JSON patch must be an array of objects
```
### json.exception.parse_error.105
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.
[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
```
```
[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
```
```
[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
```
### json.exception.parse_error.114
The parsing of the corresponding BSON record type is not implemented (yet).
The iterators passed to constructor `basic_json(InputIT first, InputIT last)` are not compatible, meaning they do not belong to the same container. Therefore, the range (`first`, `last`) is invalid.
[json.exception.invalid_iterator.201] iterators are not compatible
```
### json.exception.invalid_iterator.202
In an erase or insert function, the passed iterator @a pos 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.
[json.exception.invalid_iterator.202] iterator does not fit current value
```
```
[json.exception.invalid_iterator.202] iterators first and last must point to objects
```
### json.exception.invalid_iterator.203
Either iterator passed to function `erase(IteratorType` first, IteratorType last) 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.
[json.exception.invalid_iterator.203] iterators do not fit current value
```
### json.exception.invalid_iterator.204
When an iterator range for a primitive type (number, boolean, or string) is passed to a constructor or an erase function, this range has to be exactly (`begin(),` `end()),` because this is the only way the single stored value is expressed. All other ranges are invalid.
[json.exception.invalid_iterator.204] iterators out of range
```
### json.exception.invalid_iterator.205
When an iterator for a primitive type (number, boolean, or string) is passed to an erase function, the iterator has to be the `begin()` iterator, because it is the only way to address the stored value. All other iterators are invalid.
[json.exception.invalid_iterator.209] cannot use offsets with object iterators
```
### json.exception.invalid_iterator.210
The iterator range passed to the insert function are not compatible, meaning they do not belong to the same container. Therefore, the range (`first`, `last`) is invalid.
[json.exception.invalid_iterator.213] cannot compare order of object iterators
```
### json.exception.invalid_iterator.214
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 `begin()`.
[json.exception.invalid_iterator.214] cannot get value
```
## Type errors
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.
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.
[json.exception.type_error.301] cannot create object from initializer list
```
### json.exception.type_error.302
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.
[json.exception.type_error.302] type must be object, but is null
```
```
[json.exception.type_error.302] type must be string, but is object
```
### json.exception.type_error.303
To retrieve a reference to a value stored in a `basic_json` object with `get_ref`, the type of the reference must match the value type. For instance, for a JSON array, the `ReferenceType` must be `array_t &`.
[json.exception.type_error.312] cannot use update() with array
```
### json.exception.type_error.313
The `unflatten` 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.
Calling `dump()` on a JSON value containing an ISO 8859-1 encoded string:
```
[json.exception.type_error.316] invalid UTF-8 byte at index 15: 0x6F
```
!!! tip
- Store the source file with UTF-8 encoding.
- Pass an error handler as last parameter to the `dump()` function to avoid this exception:
-`json::error_handler_t::replace` will replace invalid bytes sequences with `U+FFFD`
-`json::error_handler_t::ignore` will silently ignore invalid byte sequences
### json.exception.type_error.317
The dynamic type of the object cannot be represented in the requested serialization format (e.g. a raw `true` or `null` JSON object cannot be serialized to BSON)
[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is null
```
Serializing `#!json [1,2,3]` to BSON:
```
[json.exception.type_error.317] to serialize to BSON, top-level type must be object, but is array
```
!!! tip
Encapsulate the JSON value in an object. That is, instead of serializing `#!json true`, serialize `#!json {"value": true}`
## Out of range
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.
The special array index `-` 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.
