json_decode returns null on JSON that looks fine
json_decode() returns NULL on a string that prints as valid JSONShort 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.
Fix it fast
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)));2Match what you see, then jump to its fix
- 1
The hex output begins with efbbbfA UTF-8 byte order mark sits at the start of the stringFix - 2
String 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
json_last_error() returns JSON_ERROR_UTF8The bytes are not valid UTF-8 (a Latin-1 or Windows-1252 file)Fix
- 1
What does the error look like?
json_decode() returns NULL on a string that prints as valid JSONjson_last_error_msg(): Syntax errorjson_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
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
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
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
json_decode() gives NULL for JSON that looks valid
Syntax error
json_decode returns null when it cannot decode the input, and also when the JSON really is null.
4 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack 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 fixBack end
Apache returns 500 with Premature end of script headers
500 Internal Server Error
Apache ran your script, but the script printed no valid HTTP header before its output.
3 causes, each with a fixBack end
Apache returns 503 or 504 because PHP-FPM did not answer in time
Error dispatching request
Apache sent the request to PHP-FPM and gave up waiting.
3 causes, each with a fixBack end
AWS SDK for PHP cannot get credentials from the instance profile metadata server
Error retrieving credentials from the instance profile metadata server.
The SDK tries the EC2 instance metadata service when it has no valid credentials from anywhere earlier in its chain.
4 causes, each with a fix