Supabase Errors

The PGRST100 error occurs when Supabase (PostgREST API) cannot find the table you're trying to access. This can happen when the table is in a different schema, has a case-sensitivity issue, doesn't exist yet, or when the PostgREST schema cache hasn't been refreshed.

This error occurs when attempting to sign up a user with an email address already registered in Supabase Auth. The behavior depends on your email confirmation settings.

Supabase Realtime channel subscription fails due to authentication, permissions, replication settings, or RLS policy misconfigurations. This error occurs when the client cannot establish a successful subscription to monitor real-time database changes or broadcast messages.

This error occurs when your Supabase project exceeds its configured email sending rate limit. By default, the built-in email service allows only 2-4 emails per hour, while custom SMTP providers support 30+ emails per hour. Upgrading to a custom email provider or adjusting rate limits can resolve this.

This error occurs when your application makes too many requests to Supabase Auth or Management API within a short timeframe, triggering built-in rate limiting that returns a 429 status code.

This error occurs when attempting to link an OAuth identity that is already associated with another user account in Supabase Auth, commonly when converting anonymous users to verified accounts.

This error occurs when attempting to sign up a user with an email address already registered in Supabase Auth. Behavior varies depending on email confirmation settings.

The "PGRST000: Could not connect to the database" error occurs when PostgREST (Supabase's REST API layer) cannot establish an initial connection to your PostgreSQL database. This typically happens due to database being paused, incorrect credentials, configuration issues, or infrastructure problems. The error indicates that the database service is unreachable or misconfigured.

The "over_sms_send_rate_limit: SMS send rate limit exceeded" error occurs when Supabase Auth blocks SMS sending due to rate limiting. This protection prevents SMS bombing attacks and excessive usage, typically triggered by too many authentication attempts to a single phone number within a short time period or exceeding overall project SMS quotas.

The "PGRST001: Connection to the database was lost" error occurs when PostgREST (Supabase's REST API layer) cannot maintain a connection to your PostgreSQL database. This typically happens due to network issues, database server problems, connection pool exhaustion, or infrastructure maintenance. The error returns HTTP status 503 (Service Unavailable) and indicates a temporary loss of database connectivity.

The "request_timeout: Processing request took too long" error occurs when Supabase Auth API requests exceed their maximum processing time limit. This typically happens with complex authentication flows, high server load, or network issues between your application and Supabase servers.

This error occurs when attempting to link an OAuth identity to an existing user via linkIdentity() while the manual linking feature is disabled in your Supabase project settings. Manual linking must be explicitly enabled for security reasons.

Supabase Auth rejects an email address during signup or authentication due to format validation rules. This typically occurs when the email format violates Supabase's validation requirements, which may be stricter than standard RFC 5322 specifications.

This PostgreSQL error occurs when attempting to insert a duplicate value into a column with a unique constraint in your Supabase database. The constraint could be a primary key, unique index, or explicitly defined unique column.

Supabase Auth returns the "bad_json" error when the HTTP request body sent to authentication endpoints contains malformed JSON or cannot be parsed. This error prevents authentication operations like sign-up, sign-in, or token refresh and requires fixing the JSON payload structure before retrying.

This error occurs when the "aud" (audience) claim in your JWT token doesn't match what Supabase expects during authentication validation. Supabase requires JWTs to have an audience claim set to "authenticated" for standard user sessions.

The "StorageApiError: Object not found" error occurs when Supabase Storage cannot locate a file or object you're trying to access. This typically happens when referencing files that don't exist, have been deleted, or have incorrect paths. The fix involves verifying file paths, checking bucket permissions, and ensuring proper file upload procedures.

The MFA enrollment process detected a different IP address during verification. This security measure prevents unauthorized factor enrollment. Complete the entire enrollment flow from the same network to resolve it.

The PKCE flow state expires after 5 minutes of inactivity. This error occurs when users take too long to complete the OAuth authentication callback or attempt to use an expired authorization code. Complete the authentication flow within 5 minutes or restart the login process to fix this.

This error occurs when Supabase Auth rejects a multi-factor authentication (MFA) verification attempt, typically due to invalid codes, rate limiting, or custom verification hooks blocking the authentication flow.

This error occurs when a user with an active ban attempts to authenticate or refresh their session in Supabase. Banned users cannot log in or refresh tokens until their ban expires or is lifted.

The "sms_send_failed: Sending SMS failed" error occurs when Supabase Auth cannot send SMS messages for phone authentication or OTP verification. This typically happens due to misconfigured SMS provider settings, rate limiting, invalid phone numbers, or insufficient credits with the SMS service provider.

This error occurs when Supabase cannot find a valid refresh token during authentication. Refresh tokens are used to obtain new access tokens without requiring users to re-enter credentials. The fix typically involves checking token storage, session management, and authentication flow configuration.

The "anonymous_provider_disabled: Anonymous sign-ins are disabled" error occurs when Supabase Auth attempts anonymous authentication but anonymous sign-ins are not enabled in the project settings. This prevents users from creating temporary anonymous accounts until anonymous authentication is properly configured and enabled.

The "PGRST117: HTTP verb not allowed" error occurs when you attempt to use an HTTP method (GET, POST, PUT, DELETE, etc.) that is not permitted for a specific Supabase API endpoint or database resource. This typically happens due to Row Level Security (RLS) policies, table permissions, or incorrect API usage.

The "EdgeFunctionError: Function invocation timeout" error occurs when a Supabase Edge Function exceeds its maximum execution time limit. This typically happens with long-running operations, infinite loops, or inefficient code that takes too long to complete within the function's time constraints.

This error occurs when signing up or logging in with an OAuth provider (Google, GitHub, etc.) if the provider's email hasn't been verified by that provider. OAuth providers require verified emails to prevent account takeover attacks. The solution involves verifying the email with the OAuth provider or configuring Supabase's email verification settings.

This error occurs when attempting to sign in with an OAuth provider that has not been enabled in your Supabase project settings. The fix requires enabling the provider in the Supabase Dashboard under Authentication settings.

The "phone_provider_disabled: Phone signups are disabled" error occurs when Supabase Auth attempts phone-based authentication but phone signups are not enabled in the project settings. This prevents users from signing up or logging in with phone numbers until phone authentication is properly configured and enabled.

Supabase responds with "user_not_found: User could not be found" when the identifier you supplied (email, phone, or OAuth provider) does not match any row inside auth.users. The fix is usually to confirm the user exists in the right project, create or restore the missing account, and call the correct sign-in flow so Supabase is looking for the provider you expect.

Supabase returns 'unexpected_failure: Unexpected service failure' (HTTP 500) when the Auth service encounters a problem during user operations, usually caused by broken database triggers, foreign key constraint violations, permission errors on custom tables, or insufficient project resources. The fix involves identifying the database issue through logs, fixing triggers and constraints, and ensuring proper security permissions.

Supabase (PostgREST) rejects any POST/PATCH/PUT request that transports a body without so much as a Content-Type header. The 405/PGRST101 response is PostgREST telling you it has no idea how to deserialize the payload, so the mutation never reaches the database. Setting the right media type fixes the error instantly.

Supabase throws `signup_disabled: Signups are disabled` when the project explicitly refuses to create new accounts, so every signUp, OAuth, or OTP request returns a 400. Re-enable the "Allow new users to sign up" toggle or clear the same flag in self-hosted deployments to allow account creation again.

The "validation_failed: Input validation failed" error occurs when data being inserted or updated in Supabase fails to meet database constraints, schema validation rules, or data type requirements. This error typically indicates issues with data format, missing required fields, or violations of database constraints like foreign keys, unique constraints, or check constraints.

Supabase returns "email_not_confirmed: Email has not been confirmed" when you attempt to sign in with an account whose email address has not been verified. The fix is to either disable email confirmation in your auth settings for development, resend the confirmation email to the user, or ensure they have clicked the confirmation link in their inbox.

Supabase returns this error when a user attempts to access a protected resource without meeting the required Multi-Factor Authentication (MFA) level. Authenticator Assurance Level (AAL) is a security concept that defines how strongly a user has authenticated, and certain operations require higher assurance levels than basic password authentication.

The "EdgeFunctionError: Boot error" occurs when a Supabase Edge Function fails to initialize or start properly. This typically happens due to configuration issues, missing dependencies, syntax errors in the function code, or environment problems that prevent the Deno runtime from successfully booting the Edge Function.

This error occurs during Supabase authentication when the code_verifier stored from the initial PKCE request doesn't match the one sent during token exchange. It typically indicates the code verifier wasn't persisted correctly, or the authentication request was completed on a different browser/device than where it started.

Supabase surfaces PostgREST’s PGRST107 code whenever it cannot decode or verify the bearer JWT, so the request is rejected before any policies or SQL run. This article walks through inspecting the Authorization header, checking the JWKS/signing key configuration, and refreshing tokens after key rotation.

Supabase returns 'invite_not_found: Invite has expired or already been used' when a user attempts to accept an email invitation that is no longer valid. This occurs when the invitation token has expired (default 24-48 hours), has already been redeemed, or was manually revoked. The fix involves resending a fresh invitation, extending the token expiry, or checking for duplicate acceptances.

The "REALTIME_TIMEOUT: Connection to Realtime server timed out" error occurs when Supabase Realtime cannot establish or maintain a WebSocket connection to the realtime server. This typically happens due to network issues, firewall restrictions, browser extensions, or server-side configuration problems. The error prevents realtime features like live subscriptions, presence, and broadcast channels from working.

Supabase (PostgREST) returns PGRST102 when the JSON payload sent to a REST endpoint is malformed, contains syntax errors, or violates schema constraints. This error prevents the request from reaching the database and requires fixing the JSON structure before resubmitting.

Supabase returns "flow_state_not_found: PKCE flow state could not be found" when the OAuth authorization flow state is missing, expired, or corrupted. This typically happens when users take too long to complete social login, when browser sessions are cleared mid-flow, or when PKCE code verifiers don't match. The fix involves adjusting flow timeouts, preserving session storage, and ensuring consistent PKCE implementation.

This error occurs when attempting to authenticate or perform actions with a Supabase user whose phone number has not been verified via OTP. Users must complete SMS verification before proceeding.

Supabase returns 'identity_not_found: Identity does not exist' when attempting to link, unlink, or reference an identity that has been deleted or doesn't exist in the auth.identities table. This typically occurs during OAuth linking operations, user merging, or when identities are manually removed from the database. The fix involves verifying the identity exists, recreating it if needed, and ensuring proper linking procedures.

Supabase returns 'bad_oauth_callback: OAuth callback contains an error' when the OAuth provider redirects back with an error parameter in the URL. This typically happens when the user denies permission, the OAuth flow times out, or there's a configuration mismatch between your Supabase project and the OAuth provider.

This error occurs when email authentication is disabled in Supabase Auth settings, preventing new users from signing up with email/password. Enable email provider in your project dashboard to allow email-based signups.

This error occurs when attempting to access a Supabase Storage bucket that does not exist, has an incorrect name, or requires permissions you lack. It commonly appears during file upload, download, or bucket operations when the specified bucket cannot be found or accessed.

This error occurs when attempting to update protected user fields for SSO-managed accounts in Supabase. Users authenticated via SAML SSO have immutable email and phone fields controlled by their identity provider.

This error occurs when there's a network or routing issue between your client and Supabase's edge gateway. The relay layer handles authentication, routing, and traffic management for Edge Functions.

This error occurs when attempting to unlink or delete a user's only authentication identity in Supabase. Users must have at least one identity to maintain account access.

Supabase rejects password updates where the new password string matches the existing one and responds with "same_password: New password must be different." The API re-authenticates the submitted password before writing, so the request finishes with HTTP 422 whenever both values align.

The "mfa_verification_failed: MFA verification failed" error occurs when Supabase Auth cannot verify a multi-factor authentication code. This typically happens due to incorrect TOTP codes, timing synchronization issues, expired codes, or rate limiting from too many failed verification attempts.

This error occurs when attempting to access Supabase Storage without proper Row-Level Security (RLS) policies or valid authentication. The fix involves creating appropriate RLS policies on the storage.objects table and ensuring your client sends a valid JWT token.

This Supabase Authentication error occurs when you attempt to use one-time password (OTP) authentication without enabling it in your project settings. The fix requires enabling email or phone OTP providers in the Supabase dashboard and properly configuring your authentication flow.

Supabase rejects requests with a bad_jwt error when the JWT token in the Authorization header cannot be validated. This typically happens when using the wrong token type, an expired token, or a malformed JWT structure. This guide shows how to identify and fix JWT validation issues.

Supabase responds with "not_admin: User is not an admin" when you attempt to call an admin-only operation using a regular user JWT instead of a service_role key. Admin operations like createUser, updateUserById, and deleteUser require elevated privileges that bypass Row Level Security and can only be executed on trusted servers with the service_role key.

This error occurs when a Supabase auth hook exceeds its execution time limit - 2 seconds for Postgres hooks or 5 seconds for HTTP hooks. The authentication flow is interrupted to prevent delays.

This error occurs when Supabase detects a refresh token being reused outside the allowed reuse interval, typically due to race conditions in SSR applications or network issues causing stale tokens to be retried.

Supabase Auth restricts email sending to pre-authorized addresses when using the default email provider. This error occurs when trying to send authentication emails to addresses not in your project's authorized list.

Supabase requires reauthentication before allowing users to change their password or email address. This security measure prevents unauthorized account modifications when the Secure password change or Secure email change options are enabled.

The Supabase API requires an Authorization header with a JWT token for authenticated requests. This error occurs when requests to protected endpoints, Edge Functions, or Row Level Security policies don't include a valid JWT token in the Authorization header.

This error occurs when unlinking an identity would cause a user's account to switch to an email address that's already in use by another user. Supabase enforces unique email addresses across all user accounts.

Supabase returns "otp_expired: OTP has expired" when you attempt to verify a one-time password (OTP) that has exceeded its expiration window. By default, OTP codes are valid for 1 hour. The fix is to request a new OTP, check your configuration for timeout settings, or verify you are using the correct OTP type parameter in your authentication call.

This error occurs during Supabase OAuth authentication when the state parameter used for CSRF protection is missing, invalid, or doesn't match between the initial request and OAuth provider callback. It typically indicates a session mismatch, hostname misconfiguration, or cookie persistence issue.

The "mfa_challenge_expired: MFA challenge has expired" error occurs when you attempt to verify a multi-factor authentication challenge that has exceeded its validity window. Supabase challenges have a limited lifetime (typically 5-10 minutes), and verification requests submitted after expiration are rejected, requiring you to create a new challenge.

The "mfa_factor_not_found" error in Supabase occurs when attempting to challenge, verify, or manage an MFA factor that doesn't exist or is no longer available. This typically happens during incomplete enrollments, page refreshes before verification completes, or when trying to use an unenrolled factor ID.

The mfa_factor_name_conflict error occurs when you try to enroll a new MFA factor with a friendly name that's already in use by another factor for the same user. This happens because Supabase enforces unique friendly names to help users distinguish between multiple authentication methods.

The CAPTCHA verification failed during Supabase authentication, typically because the CAPTCHA token was not passed correctly to the auth request or the token has expired. Ensure your frontend is passing the captchaToken in the options parameter and that your Supabase CAPTCHA provider keys are correctly configured.

This error occurs when Supabase Auth fails to authenticate a user due to invalid email or password. The error intentionally doesn't distinguish between wrong passwords and non-existent users for security reasons.

This error occurs when multiple simultaneous requests try to modify the same database rows. Supabase uses PostgreSQL's SERIALIZABLE isolation level, which detects these conflicts and rejects one transaction to maintain data integrity.

This error occurs when attempting to sign up, link, or update a phone number that is already associated with another user account in Supabase Auth. This can happen during signup, MFA enrollment, or when updating user phone numbers.

Supabase throws this error when you attempt OAuth signup with a provider that hasn't been enabled in your project settings. Enable the provider in the Supabase dashboard and verify credentials are correct.

This error occurs when attempting to upload a file to Supabase Storage at a path where a file already exists. By default, Supabase rejects file uploads that would overwrite existing resources. The solution is to enable the upsert option to allow file replacement or delete the existing file first.

PostgreSQL error 42501 indicates insufficient privileges to access a table, commonly caused by missing RLS policies, incorrect grants, or authentication issues in Supabase. This error occurs when your application tries to read, insert, or update data without proper permissions configured.

This error occurs when attempting to upload a file or access an object in Supabase Storage with an invalid file path. Common causes include special characters in the file name, empty path strings, non-ASCII characters that get URL-encoded, or structural issues in the path format.

This error occurs when a scalar subquery in your SQL query returns multiple rows instead of the expected single row. In Supabase, this commonly happens during INSERT/UPDATE operations with triggers, RLS policies, or computed columns.

Users can enroll up to 10 MFA factors in Supabase Auth. When this limit is reached, attempting to enroll another factor fails with the 'too_many_enrolled_mfa_factors' error. This commonly happens when users cancel enrollment flows, leaving unverified factors that count toward the limit.

The "PGRST118: Could not find function" error occurs when you attempt to call a PostgreSQL function via Supabase's PostgREST API, but the function cannot be found in the schema cache. This typically happens after creating a new function, due to schema cache not being refreshed, or when the function lacks proper permissions.

The "REALTIME_DISCONNECT: Websocket disconnected from Realtime server" error occurs when a WebSocket connection to Supabase Realtime unexpectedly closes. This can happen due to network interruptions, server-side timeouts, authentication token expiration, or quota limits. Implementing proper reconnection logic with exponential backoff is essential for maintaining reliable realtime features.

A foreign key constraint violation (error 23503) occurs when you try to insert or update a record with a reference that doesn't exist in the parent table. In Supabase, this PostgreSQL error prevents orphaned data and maintains database integrity.

PostgreSQL error 42P01 occurs when you query or reference a table that doesn't exist in your database. Fix it by verifying the table name spelling, checking the schema, running migrations, or quoting identifiers for case-sensitive names.

This error occurs when a request is sent to a Supabase Edge Function that doesn't exist, hasn't been deployed, or the URL is incorrect. It typically returns a 404 HTTP response with error code EF002.

The PGRST103 error (HTTP 416: Range Not Satisfiable) occurs when you request a data range using .range() or pagination parameters that exceeds the available rows in your Supabase table. This guide walks through validating pagination bounds, fetching total counts before querying, and handling out-of-bounds requests gracefully.

This error occurs when you attempt to create or update a user password in Supabase Auth that doesn't meet the configured password strength requirements. Your password may be too short, lack required character types, or be a known compromised password.

The "session_not_found" error occurs when Supabase Auth detects that the session ID in your JWT token no longer exists in the auth.sessions table. This typically happens due to session expiration, token refresh failures, or URL mismatches between your Supabase configuration and frontend application.