App Finishers

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:

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:

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

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?

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.