Fix guide · updated 2026-11-17
Supabase "invalid claim: missing sub claim" (403 bad_jwt)
AuthApiError: invalid claim: missing sub claim · 403 · bad_jwt
Your Edge Function or server code calls supabase.auth.getUser() and gets AuthApiError: invalid claim: missing sub claim (status 403, code bad_jwt). Supabase Auth was asked "which user is this?" with your project's anon key, or its service_role key, instead of a signed-in user's token. Those keys are valid tokens, but they don't belong to any user. Most of the time, nobody was signed in when your app called the function.
What the error means
A signed-in user's access token is a JWT that carries "sub", the user's id. The legacy anon and service_role keys are JWTs too, but they carry a role, not a user id. getUser() asks Supabase Auth's /user endpoint for the user behind a token, and for a token without sub Auth answers:
403 {"code":403,"error_code":"bad_jwt","msg":"invalid claim: missing sub claim"}
In our test, the anon key and the service_role key both got exactly that, and a signed-in user's access token got the user back. The same check runs on Auth's other calls that need a user: the requests behind updateUser() (PUT /user) and sign-out (POST /logout) got the same 403 when we sent them with the anon key. auth.getClaims(<anon key>) failed the same way too: for a token signed with the project's legacy JWT secret, supabase-js checks it by calling getUser.
1. Why your function received the anon key
supabase-js puts a token in the Authorization header of every call. With a session, it's the user's access token. Without one, a client made with the legacy anon key (the long key that starts with eyJ) sends the anon key itself. Edge Functions' Verify JWT check lets that through, because the anon key is a valid token for your project. So your function runs, passes the header on to Auth, and Auth refuses it. This is the pattern AI tools often write:
import { createClient } from 'npm:@supabase/supabase-js@^2'
import { corsHeaders } from 'npm:@supabase/supabase-js@^2/cors'
Deno.serve(async (req) => {
if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders })
const supabase = createClient(Deno.env.get('SUPABASE_URL')!, Deno.env.get('SUPABASE_ANON_KEY')!, {
global: { headers: { Authorization: req.headers.get('Authorization')! } },
})
const { data: { user }, error } = await supabase.auth.getUser()
if (error) {
return new Response(JSON.stringify({ error: error.message }), {
status: 500,
headers: { ...corsHeaders, 'Content-Type': 'application/json' },
})
}
return new Response(JSON.stringify({ id: user!.id }), {
headers: { ...corsHeaders, 'Content-Type': 'application/json' },
})
})
In our test, with Verify JWT on:
- Called with
supabase.functions.invokewhile signed out: the function received the anon key and answered 500{"error":"invalid claim: missing sub claim"}. The app itself only sawEdge Function returned a non-2xx status code. - Called by hand (curl style) with the anon key as the Bearer token: the same 500.
- Called while signed in:
{"id":"…"}.
So look at when your app makes the call: on a page that people can open without signing in, before your sign-in step, or after the session ran out and could not be refreshed (supabase-js then has no session and falls back to the anon key, see JWT expired). Testing a function by hand with the anon key gives the same error.
2. With a publishable key you get a different error
If your app's client is made with a new publishable key (sb_publishable_…), supabase-js 2.119 does not send the key as a Bearer token to Edge Functions. In our test, a signed-out functions.invoke from such a client arrived with no Authorization header at all, and Verify JWT stopped it before the function ran: 401 Missing authorization header. That one has its own guide: "Missing authorization header". The cause is the same: nobody was signed in.
3. The fix in your function: no user means 401
Read the token from the request, ask Auth for its user, and answer 401 when there is none, instead of a 500 that hides the reason:
import { createClient } from 'npm:@supabase/supabase-js@^2'
import { corsHeaders } from 'npm:@supabase/supabase-js@^2/cors'
// The default publishable key (new keys), else the legacy anon key: both are in Supabase's default secrets.
const publishableKeys = JSON.parse(Deno.env.get('SUPABASE_PUBLISHABLE_KEYS') ?? '{}')
const supabase = createClient(Deno.env.get('SUPABASE_URL')!, publishableKeys['default'] ?? Deno.env.get('SUPABASE_ANON_KEY')!)
const json = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { ...corsHeaders, 'Content-Type': 'application/json' } })
Deno.serve(async (req) => {
if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders })
// The caller's token: a signed-in user's access token, or (signed out) the project's anon key, or nothing.
const token = (req.headers.get('Authorization') ?? '').replace(/^Bearer\s+/i, '')
if (!token) return json({ error: 'Sign in first' }, 401)
const { data, error } = await supabase.auth.getUser(token)
if (error || !data.user) {
// « invalid claim: missing sub claim » = the token is a project key (anon or service_role), not a user's token
return json({ error: 'Sign in first', reason: error?.message ?? 'no user' }, 401)
}
return json({ id: data.user.id, email: data.user.email })
})
Keep Verify JWT on for this function (the default). In our test:
- Signed out (the anon key): 401
{"error":"Sign in first","reason":"invalid claim: missing sub claim"}. - The service_role key as the Bearer token: the same 401. The service_role key is not a user either.
- Signed in, through
functions.invokeor by hand with the user's access token:{"id":"…","email":"…"}.
Passing the token to getUser(token) does the same thing as forwarding the header to a client and calling getUser(): in our test both sent the anon key to Auth. The difference is that you can see which token you check, and stop early when there is none.
Supabase's own docs now also show a helper for this, withSupabase({ auth: 'user' }, …) from npm:@supabase/server, which checks the caller's token before your code runs. We haven't tested it; the function above is the smallest change to the pattern from section 1.
4. In your app: don't call it signed out
import { FunctionsHttpError } from '@supabase/supabase-js'
const { data: { session } } = await supabase.auth.getSession()
if (!session) {
// nobody is signed in: send the user to your sign-in page first
return
}
const { data, error } = await supabase.functions.invoke('whoami')
if (error instanceof FunctionsHttpError && error.context.status === 401) {
// the session is gone: ask the user to sign in again
}
In our test, getSession() on a signed-out client returned session: null without sending any request, and the function's 401 reached the app as a FunctionsHttpError whose context.status was 401.
5. Testing by hand: use a user's token, not the anon key
To call your function as a signed-in user from a terminal, sign a test user in first. This is the request signInWithPassword makes:
curl -X POST 'https://YOUR-PROJECT.supabase.co/auth/v1/token?grant_type=password' \
-H 'apikey: YOUR-PUBLISHABLE-OR-ANON-KEY' -H 'Content-Type: application/json' \
-d '{"email":"test@example.com","password":"the test password"}'
Copy access_token from the answer and send it as the Bearer token:
curl -X POST 'https://YOUR-PROJECT.supabase.co/functions/v1/whoami' \
-H 'Authorization: Bearer THE-ACCESS-TOKEN' -H 'Content-Type: application/json' -d '{}'
The access token expires after an hour by default. With the anon key in that header instead, you test the signed-out case.
Other messages from the same call
This endpoint requires a valid Bearer token(401,no_authorization): the request reached Auth with noAuthorizationheader at all.invalid JWT: unable to parse or verify signature, token signature is invalid: signature is invalid(403,bad_jwt): a token signed with another secret, for example a token from another Supabase project.invalid claim: sub claim must be a UUID(400,bad_jwt): a token signed with your project's JWT secret whosesubisn't a Supabase user id, for example one your own server made.Auth session missing!(AuthSessionMissingError):getUser()with no argument, on a client with no session and noAuthorizationheader. supabase-js doesn't send a request at all. See "Auth session missing!".
If an AI tool built your app
Give your tool this prompt:
My Supabase Edge Function calls auth.getUser() and fails with "invalid claim: missing sub claim" (403 bad_jwt), because it receives the anon key when nobody is signed in. Change the function: read the token from the Authorization header (strip "Bearer "); if there is none, return 401 {"error":"Sign in first"}; call supabase.auth.getUser(token) and, if there is an error or no user, return 401 {"error":"Sign in first"} instead of 500; keep the CORS headers on every response and keep verify_jwt on. In the app: before supabase.functions.invoke, check supabase.auth.getSession() and send signed-out users to sign in; when the function answers 401, ask the user to sign in again. Don't use the service_role key to get around the error.
Not quite your error?
- "Missing authorization header" from your function: no token reached it at all.
- "JWT expired": the user's token ran out.
- "Edge Function returned a non-2xx status code": read your function's real answer.
- "User not allowed" from
auth.admincalls: admin calls need the secret key.
Still stuck?
Open Supabase's Auth log (Logs, Log Type Auth) and find the 403 on /user. In our test, Auth logged it as 403: invalid claim: missing sub claim with error_code bad_jwt. Then check what your app sent: in the browser's Network tab, open the call to your function and look at its Authorization header. If it's your anon key, nobody was signed in when the call went out.
Other Supabase problems? See Supabase fixes.