Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

json_decode() gives NULL for JSON that looks valid

Errorjson_decode() returns NULL

Short answer

json_decode returns null when it cannot decode the input, and also when the JSON really is null. Ask json_last_error_msg for the reason, or pass JSON_THROW_ON_ERROR to get an exception. The usual causes are JavaScript-style syntax, malformed UTF-8 bytes, or nesting deeper than the depth argument.

  • Applies to PHP 8.3, PHP 8.4
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the decode result next to the error message. It names the cause directly.

    $data = json_decode($json, true);
    var_dump($data, json_last_error(), json_last_error_msg());
  2. 2Match what you see, then jump to its fix

    1. 1Syntax errorThe text is JavaScript, not JSONFix
    2. 2Malformed UTF-8 characters, possibly incorrectly encodedThe string contains invalid UTF-8Fix
    3. 3Maximum stack depth exceededThe data is nested deeper than the depth argumentFix
    4. 4json_last_error_msg() reads No error, yet the result is null.The JSON really is nullFix

What does the error look like?

  • json_decode() returns NULL
  • Syntax error
  • Malformed UTF-8 characters, possibly incorrectly encoded
  • Maximum stack depth exceeded

Cause 1 of 4

The text is JavaScript, not JSON

1Check

JSON allows only double-quoted strings and double-quoted keys, and no trailing comma. The manual lists single quotes, bare keys and trailing commas as inputs that give null.

var_dump(json_decode("{ 'bar': 'baz' }"));
var_dump(json_decode('{ bar: "baz" }'));
var_dump(json_decode('{ "bar": "baz", }'));

2Fix

Fix the producer so it emits real JSON, for example with json_encode or JSON.stringify, instead of patching the string in the reader.

echo json_encode(['bar' => 'baz']);   // {"bar":"baz"}

3Verify

The decoded value is no longer null and the error is empty.

php -r 'var_dump(json_decode("{\"bar\":\"baz\"}"), json_last_error_msg());'

Confirmed by php.net

Did this fix it?

Cause 2 of 4

The string contains invalid UTF-8

1Check

The error constant for this case says malformed UTF-8 characters, possibly incorrectly encoded. Text read from a Latin-1 file or a legacy database column may be the source. Confirm it with the error code.

json_decode($json);
var_dump(json_last_error() === JSON_ERROR_UTF8);

2Fix

Convert the data to UTF-8 at the source. If losing the bad bytes is acceptable, PHP 7.2 and later can replace them while decoding.

$data = json_decode($json, true, 512, JSON_INVALID_UTF8_SUBSTITUTE);

3Verify

The call returns your array and json_last_error_msg() reads No error.

var_dump(json_last_error_msg());

Confirmed by php.net

Did this fix it?

Cause 3 of 4

The data is nested deeper than the depth argument

1Check

The third argument of json_decode is the maximum nesting depth. The manual's own example shows a depth of 3 failing on data that a depth of 4 accepts.

var_dump(json_decode($json, true, 4));
var_dump(json_decode($json, true, 3), json_last_error_msg());

2Fix

Raise the depth argument to cover the real structure, or ask why the payload is nested that deeply.

$data = json_decode($json, true, 1024);

3Verify

The error message reads No error.

var_dump(json_last_error_msg());

Confirmed by php.net

Did this fix it?

Cause 4 of 4

The JSON really is null

1Check

The manual says unquoted null decodes to null, so a null result alone does not prove a failure. Look at the raw input.

var_dump($json);
var_dump(json_decode($json), json_last_error() === JSON_ERROR_NONE);

2Fix

Treat null as a valid value when there is no error, and check the error code, not the result, to detect failure.

$data = json_decode($json, true);
if ($data === null && json_last_error() !== JSON_ERROR_NONE) {
    throw new RuntimeException(json_last_error_msg());
}

3Verify

An input of null passes, an input of { fails with a message.

php -r 'var_dump(json_decode("null"), json_last_error_msg());'

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Pass JSON_THROW_ON_ERROR so failures cannot be silent (PHP 7.3 and later).
  • Produce JSON with json_encode or a JSON library, never by string concatenation.
  • Keep one encoding, UTF-8, from the database to the HTTP response.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.