Skip to content

fix: Improve error visibility when JWK kid lookup fails - #549

Open
Minterl wants to merge 5 commits into
clerk:v2from
Minterl:v2
Open

fix: Improve error visibility when JWK kid lookup fails#549
Minterl wants to merge 5 commits into
clerk:v2from
Minterl:v2

Conversation

@Minterl

@Minterl Minterl commented May 1, 2026

Copy link
Copy Markdown

Problem

When GetJSONWebKey fails to find a matching key in the JWKS response, the current error message is:

missing json web key

This is misleading in two ways:

It implies no keys exist at all, when keys may exist but none matched the token's kid
It gives no indication of what kid was being looked for, making debugging extremely difficult

In practice this error surfaces when CLERK_SECRET_KEY is misconfigured — the JWKS endpoint returns keys for a different instance, none of which match the token's kid. The opaque error message makes this nearly impossible to diagnose withthout a few hours of source diving and manual tracing with delve.

Fix

Distinguish between two failure modes and include the kid being searched for in both:

"other keys found that did not match" => indicates wrong Clerk instance, key rotation, or misconfigured secret key
"no keys returned from endpoint" => No keys returned at all → indicates JWKS fetch returned an empty response

To make these errors surfaceable via the "default" way to use this package, the middleware, I've also taken the liberty of attaching them to the request context before handing control to failure handlers.

tl;dr

Before:

  "missing json web key"

After (keys exist but none matched):

  "no json web key found for kid \"ins_xxx\": other keys found that did not match"

After (no keys returned):

  "no json web key found for kid \"ins_xxx\": no keys returned from endpoint"

@Minterl
Minterl requested a review from a team as a code owner May 1, 2026 13:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant