json_last_error_msg()

Purpose

json_last_error_msg() gives you a human-readable description of what went wrong in the most recent JSON operation. PHP's JSON functions often signal failure in a vague way: json_decode() returns null and json_encode() returns false. The message tells you why. It is useful for logs, API error responses and debugging.

The manual describes it as returning the error string of the last json_validate(), json_encode() or json_decode() call that did not specify JSON_THROW_ON_ERROR.

Signature

Parameters and defaults

The function takes no parameters, so there are no defaults. It reads an internal error state that PHP updates each time one of the JSON functions runs in non-throwing mode.

Return value and failure cases

The function always returns a string.

• If the last relevant call succeeded, it returns No error.
• If the last relevant call failed, it returns a message such as Syntax error, Maximum stack depth exceeded or Malformed UTF-8 characters, possibly incorrectly encoded.

The function itself does not fail or throw. The message describes a previous call, not the call to json_last_error_msg().

Example 1: explaining a decode failure

A trailing comma is not valid JSON. json_decode() returns null, and the message explains the failure.

<?php
$data = json_decode('{"name": "Ada",}', true);
var_dump($data);
echo json_last_error_msg(), "\n";

NULL
Syntax error

Example 2: the state is replaced by the next call

The error state is not sticky. A later successful call replaces it, so the message goes back to No error.

<?php
json_decode('{bad json}');
echo json_last_error_msg(), "\n";
json_decode('{"ok":true}');
echo json_last_error_msg(), "\n";

Syntax error
No error

This is why you should read the message immediately after the call you care about. If other code decodes or encodes JSON in between, you may report the wrong problem or none at all.

Example 3: explaining an encode failure

Encoding fails when a string is not valid UTF-8. The bytes below are an invalid UTF-8 sequence, so json_encode() returns false.

<?php
$result = json_encode(["bad" => "\xB1\x31"]);
var_dump($result);
echo json_last_error_msg(), "\n";

bool(false)
Malformed UTF-8 characters, possibly incorrectly encoded

Edge cases

• A null result is not always an error. The JSON text null decodes to PHP null with no error. If you need to tell the two cases apart, check json_last_error_msg() or json_last_error() rather than testing the result alone.
• An empty string is invalid JSON. Decoding '' produces a syntax error, not an empty value.
• Depth limits count. Nesting deeper than the depth argument of json_decode() or json_encode() fails with Maximum stack depth exceeded.
• JSON_THROW_ON_ERROR bypasses this mechanism. A call that uses the flag reports problems through a JsonException. Use the exception's getMessage() and getCode() instead of the global error state.
• json_validate() also sets the state. It returns a boolean, so the message is the way to learn why validation failed when you call it without the throw flag.

Common mistakes

1. Checking too late. Calling another JSON function before reading the message overwrites the earlier error.
2. Treating the text as a stable code. The message is meant for people. For program logic, compare json_last_error() against the JSON_ERROR_* constants.
3. Assuming No error proves anything about earlier calls. It only describes the most recent relevant call.
4. Showing raw messages to end users. They are useful for developers and logs, but may expose implementation details. Map them to a friendlier response for public APIs.
5. Using it alongside JSON_THROW_ON_ERROR. Since those calls do not use the global state, the message may refer to something unrelated or be No error.

Related functions

• json_last_error() returns the numeric error code for the same state. Prefer it for branching logic.
• json_decode() and json_encode() are the main producers of errors.
• json_validate() checks syntax without building a PHP value.
• JsonException is the exception thrown when JSON_THROW_ON_ERROR is used.

Recap

json_last_error_msg() takes no arguments and returns a string describing the last non-throwing JSON call. It yields No error on success, and each new call replaces the previous state. Read it right after the call that might fail, use json_last_error() for logic, and consider JSON_THROW_ON_ERROR when exceptions suit your code better.