JWT::decode() says the kid is empty and cannot find the key
"kid" empty, unable to lookup correct keyShort answer
This message means you gave JWT::decode() an array of keys, but the token header has no kid to pick one with. For one secret or public key, pass a single Key object with its algorithm. For several keys, key the array by kid and make sure the issuer puts that kid in the token header.
Fix it fast
1Find out which cause you have
Decode only the header of the token (the first segment) and see whether it contains a kid at all.
echo "$TOKEN" | cut -d. -f1 | tr '_-' '/+' | base64 -d 2>/dev/null; echo2Match what you see, then jump to its fix
- 1
The header printed by the first step has alg and typ but no kid, and the code calls JWT::decode($jwt, $keys)An array of keys is passed, but the token has no kidFix - 2
You decode with an array keyed by kid, and the issuing code is yoursThe token was signed without a key IDFix - 3
You fetched a JSON Web Key Set from the identity provider and passed the raw arrayThe keys come from a JWKS and were not convertedFix
- 1
What does the error look like?
"kid" empty, unable to lookup correct keyUnexpectedValueException
Cause 1 of 3
An array of keys is passed, but the token has no kid
1Check
Look at the second argument of decode(). If it is a plain array, the library tries to find the key by the kid in the token header, and an empty kid gives this exact error.
grep -rn "JWT::decode" src/ app/2Fix
When you have one key, wrap it in a Key object together with the algorithm and pass that, not an array.
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
$decoded = JWT::decode($jwt, new Key($secret, 'HS256'));3Verify
Decode a fresh token; no exception should be thrown and the payload should come back.
php -r 'require "vendor/autoload.php"; var_dump(Firebase\JWT\JWT::decode($argv[1], new Firebase\JWT\Key(getenv("SECRET"), "HS256")));' "$TOKEN"Confirmed by github.com
Cause 2 of 3
The token was signed without a key ID
1Check
Find where the token is created. The key ID is the fourth argument of JWT::encode(). If it is missing, the header gets no kid.
grep -rn "JWT::encode" src/ app/2Fix
Pass the key ID when encoding, and use the same ID as the array key on the decoding side.
$jwt = JWT::encode($payload, $privateKey, 'RS256', 'kid1');
$decoded = JWT::decode($jwt, [
'kid1' => new Key($publicKey, 'RS256'),
]);3Verify
Run the header check from the first step on the new token; it should now list kid.
echo "$NEWTOKEN" | cut -d. -f1 | tr '_-' '/+' | base64 -d 2>/dev/null; echoConfirmed by github.com
Cause 3 of 3
The keys come from a JWKS and were not converted
1Check
decode() needs Key objects, not the raw JSON. Check whether the keys went through JWK::parseKeySet().
grep -rn "parseKeySet\|CachedKeySet" src/ app/2Fix
Convert the JWKS first. The result is an array that maps each kid to a Key object, which is exactly what decode() expects. A CachedKeySet can be passed straight to decode() as well.
use Firebase\JWT\JWK;
$keys = JWK::parseKeySet($jwks);
$decoded = JWT::decode($jwt, $keys);3Verify
Decode a token from the provider; its kid must exist as a key in the converted array.
php -r 'require "vendor/autoload.php"; print_r(array_keys(Firebase\JWT\JWK::parseKeySet(json_decode(file_get_contents("jwks.json"), true))));'Confirmed by github.com
How do I stop it coming back?
- Always pass the algorithm inside the Key object, so the token cannot choose it.
- Set a kid whenever you sign with more than one key, so rotation works.
- Catch UnexpectedValueException around decode() and return 401, not a 500.
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:
- Spotless LaundryAn on-demand laundry app: Flutter on a Laravel back end, with Firebase for live updates.
- EZ EstimaterConstruction quoting and job tracking for contractors, on a Laravel and Firebase stack.
- SessionBirdAn omnichannel engagement suite in Flutter: campaigns, chatbot, tickets, analytics and live calling.
Related fixes
Back end
Fatal error: Class "Firebase\JWT\JWT" not found
Class 'Firebase\JWT\JWT' not found
PHP cannot find the class because the package is not installed, the Composer autoloader is never loaded, or the file lacks a use statement.
3 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