Maaz Zindani

Loading the index…

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

json_decode returns null on JSON that looks fine

Errorjson_decode() returns NULL on a string that prints as valid JSON

Short answer

If the string has more bytes than visible characters, something invisible is in it. A byte order mark (EF BB BF) at the start, a zero-width or non-breaking space, or invalid UTF-8 all stop json_decode. Look at the first bytes, strip the extra characters, and read json_last_error_msg for the type.

  • 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 error and the first bytes of the string in hex. The hex view shows what the screen hides.

    $data = json_decode($raw);
    var_dump(json_last_error_msg(), bin2hex(substr($raw, 0, 8)));
  2. 2Match what you see, then jump to its fix

    1. 1The hex output begins with efbbbfA UTF-8 byte order mark sits at the start of the stringFix
    2. 2String length in bytes is larger than the visible length, and the hex shows bytes such as c2a0 (non-breaking space) or e2808b (zero-width space)Invisible characters that JSON does not count as whitespaceFix
    3. 3json_last_error() returns JSON_ERROR_UTF8The bytes are not valid UTF-8 (a Latin-1 or Windows-1252 file)Fix

What does the error look like?

  • json_decode() returns NULL on a string that prints as valid JSON
  • json_last_error_msg(): Syntax error
  • json_last_error() returns JSON_ERROR_UTF8

Cause 1 of 3

A UTF-8 byte order mark sits at the start of the string

1Check

EF BB BF is the UTF-8 form of U+FEFF. The JSON grammar in RFC 8259 allows only space, tab, line feed and carriage return around a value, and it says generators must not add a BOM to networked JSON. A parser may skip one, but you cannot rely on that.

var_dump(str_starts_with($raw, "\xEF\xBB\xBF"));

2Fix

Remove the BOM before decoding, and save the source file as UTF-8 without BOM if you control it.

if (str_starts_with($raw, "\xEF\xBB\xBF")) {
    $raw = substr($raw, 3);
}
$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);

3Verify

Decode again. It returns the array and json_last_error() is 0.

var_dump(json_last_error() === JSON_ERROR_NONE);

Confirmed by rfc-editor.org

Did this fix it?

Cause 2 of 3

Invisible characters that JSON does not count as whitespace

1Check

JSON whitespace is only the four characters above. Other invisible characters, often pasted from documents or web pages, are not whitespace and make the text invalid.

var_dump(strlen($raw), mb_strlen($raw, 'UTF-8'));
var_dump(preg_match('/[\x{00A0}\x{200B}\x{FEFF}]/u', $raw));

2Fix

Strip those characters outside string values, or better, fix the source that adds them. Run the decoder with JSON_THROW_ON_ERROR so a failure cannot pass as an empty result.

$clean = preg_replace('/[\x{00A0}\x{200B}\x{FEFF}]/u', '', $raw);
$data = json_decode($clean, true, 512, JSON_THROW_ON_ERROR);

3Verify

Decode the cleaned string and compare key counts with what you expect.

var_dump(is_array($data) ? count($data) : $data);

Confirmed by rfc-editor.org

Did this fix it?

Cause 3 of 3

The bytes are not valid UTF-8 (a Latin-1 or Windows-1252 file)

1Check

json_decode needs UTF-8 input. Without a flag, invalid bytes give the JSON_ERROR_UTF8 error.

var_dump(mb_check_encoding($raw, 'UTF-8'));

2Fix

Convert the text to UTF-8 first. If dropping or replacing bad bytes is acceptable, PHP has flags for it.

$raw = mb_convert_encoding($raw, 'UTF-8', 'Windows-1252');
// or accept loss of bad bytes:
$data = json_decode($raw, true, 512, JSON_INVALID_UTF8_SUBSTITUTE);

3Verify

mb_check_encoding returns true and decoding succeeds.

var_dump(mb_check_encoding($raw, 'UTF-8'), json_last_error_msg());

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • Save JSON files as UTF-8 without BOM.
  • Always decode with JSON_THROW_ON_ERROR so a failure raises JsonException.
  • Log bin2hex of the first bytes when a payload from outside fails to decode.

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.