Skip to content
Tutorials Center
My learning

Topics

PHP Reference ยท Exceptions and Errors

PHP JsonException class

Reference for PHP JsonException: thrown by json_encode() and json_decode() with JSON_THROW_ON_ERROR, how to read its code and message, and common causes.

JsonException is thrown by json_encode() and json_decode() when you pass the JSON_THROW_ON_ERROR flag and the operation fails. Without the flag these functions return false or null and you have to ask json_last_error() what happened, which is easy to forget. With the flag, a failure cannot be ignored.

The exception extends Exception. Its message is the same text json_last_error_msg() would give, and its code is one of the JSON_ERROR_* constants.

PHP
try {
    $data = json_decode("{oops", true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
    echo $e->getMessage();
}

Try it

PHP Decoding bad JSON

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

PHP Encoding failures and the old style

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Syntax

PHP
class JsonException extends Exception {}

json_encode(mixed $value, int $flags = 0, int $depth = 512): string|false
json_decode(string $json, ?bool $associative = null, int $depth = 512, int $flags = 0): mixed
Name Description
JSON_THROW_ON_ERROR Flag (added in PHP 7.3). Makes a failure throw JsonException instead of returning false or null.
getMessage() Text such as Syntax error or Malformed UTF-8 characters, possibly incorrectly encoded.
getCode() The JSON_ERROR_* constant, for example JSON_ERROR_SYNTAX (4) or JSON_ERROR_DEPTH (1).

Usage notes

  • The flag also leaves the global error state alone. With JSON_THROW_ON_ERROR, json_last_error() is neither set nor reset, so do not combine the two styles.
  • Why it matters for decoding. json_decode("null") is valid and returns null, the same value it returns for broken input. Only the exception (or json_last_error()) tells them apart.
  • Empty string is a syntax error, not an empty value.
  • Common causes: trailing commas, single quotes, unquoted keys, invalid UTF-8 bytes, NAN or INF in encoded data, nesting deeper than $depth, and resources that cannot be encoded.
  • Lenient encoding. JSON_INVALID_UTF8_SUBSTITUTE or JSON_INVALID_UTF8_IGNORE repair bad bytes instead of failing, and JSON_PARTIAL_OUTPUT_ON_ERROR substitutes unencodable values. Use them only when losing data is acceptable.
  • Checking only. json_validate() (PHP 8.3) tells you whether a string is valid JSON without building the value.
  • Wrap it at boundaries. Catch JsonException where input enters your code and rethrow your own exception with the original as $previous.