Fix guide · updated 2026-11-16
Supabase "Error running hook URI" (Custom Access Token hook)
AuthRetryableFetchError: Error running hook URI: pg-functions://postgres/public/custom_access_token_hook · 500
Sign-in fails with Error running hook URI after you, or your AI tool, turned on a Custom Access Token hook: the database function that adds something like a user role to the login token. The message only names the hook. Supabase writes the real reason in its logs. We ran Supabase's real Auth server with supabase-js 2.119, broke the hook in each common way, and wrote down what each one shows. Three surprises: the docs' revoke line, run without the grant line above it, locks everyone out; a hook that works in the SQL editor can fail for Auth, because Auth looks for your tables in another schema; and a missing row level security policy gives no error at all, only an empty role.
What the error means
Once the hook is on, Supabase Auth calls your function each time it creates an access token: at every sign-in, and again at every token refresh (about once an hour with the default settings). If the function fails, Auth creates no token and answers with a 500. In supabase-js 2.119 it arrives as AuthRetryableFetchError, with status 500 and error.code undefined, and with the same message whatever went wrong:
Error running hook URI: pg-functions://postgres/public/custom_access_token_hook
When the function ran but gave back something Auth can't use, the same 500 comes with a more precise message: output claims do not conform to the expected schema or output claims field is missing. Section 5 covers those.
1. Read the real reason in the logs
Supabase dashboard → Logs. Set Log Type to Auth and Level to error, then open the line for the failed sign-in (path /token). Under Raw JSON, the error field holds the reason. One of ours:
{"msg": "request completed", "path": "/token", "status": 500,
"error": "ERROR: permission denied for function custom_access_token_hook (SQLSTATE 42501)", …}
In our test, the Postgres log showed the same error, next to the statement Auth ran: select "public"."custom_access_token_hook"($1);. Find the start of your error field here:
permission denied for function custom_access_token_hook: section 2.permission denied for table …: section 3.relation "…" does not exist: section 4.output claims do not conform to the expected schemaoroutput claims field is missing: section 5.canceling statement due to statement timeout: section 6.function public.custom_access_token_hook(unknown) does not existor… is not unique: section 7.ERROR:followed by your own words and(SQLSTATE P0001): your function raised that error itself. Section 9 shows a better way.
No error at all, but your claim is always null? That's section 3 too.
2. "permission denied for function": Auth isn't allowed to run it
Auth runs your function as its own database role, supabase_auth_admin. A new function can be run by every role, so a fresh hook works without any grant. Supabase's examples follow it with a revoke line, so your app's users can't call the function through the API. That revoke also takes away Auth's access, unless the grant line ran too. In our test, every sign-in failed. Run all three lines:
grant execute on function public.custom_access_token_hook to supabase_auth_admin;
grant usage on schema public to supabase_auth_admin;
revoke execute on function public.custom_access_token_hook from authenticated, anon, public;
These are the lines the dashboard runs for you when you pick a Postgres function in Authentication → Auth Hooks (we read its code). If you set the hook up with the Supabase CLI's config.toml or with a migration, nothing runs them for you, so put them in the migration.
3. "permission denied for table", or a role that's always null
The function also reads your tables as supabase_auth_admin, and Supabase's defaults never give that role access to them. So any table you, a migration or an AI tool created is closed to it. Grant it (use your own table name):
grant select on table public.user_roles to supabase_auth_admin;
If row level security is on for that table (it should be), the hook needs a policy too. Without one there's no error at all: the read finds no rows. In our test the sign-in worked and the token said "user_role": null for everyone, admins included. A policy written for authenticated, like "users can read their own role", doesn't count: Postgres only applies a policy to the roles it names.
create policy "Auth can read user roles" on public.user_roles
as permissive for select to supabase_auth_admin using (true);
4. "relation … does not exist": works in the SQL editor, fails for Auth
Supabase sets Auth's role to look for tables in the auth schema, not in public. So a hook that reads from user_roles, without public., works when you test it in the SQL editor and fails for Auth with relation "user_roles" does not exist. One of the examples on Supabase's own hook page, "Add admin role", reads from profiles this way. Write public. in front of every table the hook uses, and every type or function of your own:
select role into user_role from public.user_roles
where user_id = (event->>'user_id')::uuid;
Adding set search_path = public to the function, after language plpgsql, also worked in our test.
5. "output claims …": what the function gave back
Auth expects your function to return the event it received, with claims changed. Each mistake has its own message, in the app and in the log:
output claims do not conform to the expected schema: - (root): Invalid type. Expected: object, given: null: the function returned NULL. The usual cause isjsonb_setwith a NULL value, which makes the whole result NULL. In our test it failed only for users with no row in the roles table, so it looked like "new users can't sign in". Wrap the value:coalesce(to_jsonb(user_role), 'null').output claims field is missing: the function returned the claims instead of the whole event. End it withreturn jsonb_set(event, '{claims}', claims);.output claims do not conform to the expected schema: - (root): email is required, and more lines like it: the function built new claims from scratch. Auth needsaud,exp,iat,sub,email,phone,role,aal,session_idandis_anonymous. Start fromevent->'claims'and add to it.output claims do not conform to the expected schema: - app_metadata: Invalid type. Expected: object, given: string: the function replaced a standard claim with another kind of value. Put your value in a claim of your own, likeuser_role.
A complete hook that avoids all four, with the grants from sections 2 and 3. It worked in our test, for users with and without a role:
create or replace function public.custom_access_token_hook(event jsonb)
returns jsonb
language plpgsql
stable
as $$
declare
claims jsonb := event->'claims';
user_role text;
begin
select role into user_role from public.user_roles
where user_id = (event->>'user_id')::uuid;
claims := jsonb_set(claims, '{user_role}', coalesce(to_jsonb(user_role), 'null'));
return jsonb_set(event, '{claims}', claims);
end;
$$;
6. "canceling statement due to statement timeout": 2 seconds
Auth gives the hook 2 seconds. In our test a hook that took 1.5 seconds worked, and one that took 3 seconds failed after 2 with canceling statement due to statement timeout. Every sign-in also waits for the hook, so a slow one slows every login. Keep it to one quick lookup by user id, on a column with an index or a primary key.
7. "function … does not exist" or "is not unique"
The hook's URI names one schema and one function: pg-functions://postgres/public/custom_access_token_hook means public.custom_access_token_hook. If that function was renamed, deleted or created in another schema, Auth fails with function public.custom_access_token_hook(unknown) does not exist. The (unknown) is normal: Auth doesn't say what type its value is. Create the function again, or pick the right one in Authentication → Auth Hooks.
If two functions have that name, for example one that takes json and one that takes jsonb, Auth can't choose and fails with … is not unique. Delete the one you don't use:
drop function public.custom_access_token_hook(json);
8. Sign-in works, then every query fails with role "admin" does not exist
Don't put your app's role in the role claim. Supabase uses role to choose the database role for every request. In our test, a hook that set role to "admin" let the user sign in, then every query failed with status 401, code 22023: role "admin" does not exist. Users without a row in the roles table kept authenticated and had no problem, so it looked like a bug only admins hit. Use a claim of your own, like user_role, and read it in your policies with auth.jwt() ->> 'user_role'.
9. Blocking a sign-in on purpose: return an error, don't raise one
Some hooks refuse certain users, for example a suspended account. With raise exception 'Account suspended', the app only gets the usual Error running hook URI… with status 500, and supabase-js treats it as a temporary failure. Return an error object instead:
return jsonb_build_object('error', jsonb_build_object(
'http_code', 403, 'message', 'Account suspended'));
In our test the app then got AuthApiError with status 403 and your message. Without http_code, it's a 500 again, with your message.
10. People who were already signed in
The hook runs at every refresh too, so a broken hook also hits people who are already signed in, at their next refresh. In our test, with an expired access token: after a 500 (sections 2 to 7), supabase-js tried the refresh 8 times over 26 seconds, then getSession() returned the error and kept the stored session. After the 403 from section 9, it stopped after one try, removed the session and sent a SIGNED_OUT event. So a broken hook doesn't sign anyone out, but nobody gets a new token until you fix it.
Test the hook by hand
The SQL editor doesn't run as Auth's role, so a missing grant or policy won't show there. Ask Postgres instead (change user_roles to your table). Both columns must say true:
select
has_function_privilege('supabase_auth_admin', 'public.custom_access_token_hook(jsonb)', 'execute') as can_run_hook,
has_table_privilege('supabase_auth_admin', 'public.user_roles', 'select') as can_read_table;
With row level security on, this list needs a line with SELECT (or ALL) and supabase_auth_admin in roles:
select policyname, cmd, roles from pg_policies where tablename = 'user_roles';
Then run the function the way Auth does: with Auth's schema, within 2 seconds, for a real user. Put in the email of someone who can't sign in. The rollback at the end undoes anything the function changed:
begin;
set local search_path = auth;
set local statement_timeout = '2s';
select public.custom_access_token_hook(jsonb_build_object(
'user_id', id,
'authentication_method', 'password',
'claims', jsonb_build_object(
'aud', 'authenticated', 'role', 'authenticated', 'sub', id,
'email', email, 'phone', coalesce(phone, ''),
'iss', 'test', 'iat', 1700000000, 'exp', 2000000000,
'aal', 'aal1', 'session_id', gen_random_uuid(),
'is_anonymous', is_anonymous,
'app_metadata', raw_app_meta_data, 'user_metadata', raw_user_meta_data
)
)) as hook_output
from auth.users
where email = 'someone@example.com';
rollback;
A working hook gives one row with a claims key that holds your claim. An error here is the one Auth hits (sections 4 and 6). NULL, or no claims key, is section 5. In our test, without the set local search_path line, a hook missing public. worked here and still failed for Auth: that line is what makes the test honest.
If an AI tool built your app
Read the error field first (section 1), then give your tool this prompt with it:
Supabase sign-in fails because my Custom Access Token hook, public.custom_access_token_hook, errors with: "PASTE THE ERROR FIELD FROM THE AUTH LOG". Fix only that function and its permissions, in a new migration: write public. in front of every table it reads; start from event->'claims', add our claim with jsonb_set and coalesce(..., 'null'), and return jsonb_set(event, '{claims}', claims); never change the role claim, use a claim named user_role; grant execute on the function and select on each table it reads to supabase_auth_admin, add a select policy for supabase_auth_admin on those tables, and revoke execute on the function from authenticated, anon, public. Don't change anything else.
Not quite your error?
- "Database error saving new user": a function that runs at sign-up is failing.
- "permission denied for table" in your app's own queries: the grants for your app's users.
- "Invalid Refresh Token: Refresh Token Not Found": the stored session is gone.
- "JWT expired": an old token reached the database.
Still stuck?
Turn the hook off in Authentication → Auth Hooks. Sign-ins work again, without your custom claim, so anything that reads it (like a policy on user_role) acts as if it's missing. Fix the function with the tests above, then turn the hook back on.
Other Supabase problems? See Supabase fixes.