konnosDashboard
error-codes.ts606 lines · main
1export interface ErrorCodeDefinition {
2 description: string
3 resolution?: string
4 references?: Array<{ href: string; description: string }>
5}
6
7export type ErrorCodeService = 'auth' | 'realtime'
8
9export const ERROR_CODE_DOCS_URLS: Record<ErrorCodeService, string> = {
10 auth: 'https://supabase.com/docs/guides/auth/debugging/error-codes',
11 realtime: 'https://supabase.com/docs/guides/realtime/reports',
12}
13
14export const HTTP_ERROR_CODES: Partial<
15 Record<ErrorCodeService, Record<number, { description: string }>>
16> = {
17 auth: {
18 403: {
19 description:
20 'Sent out in rare situations where a certain Auth feature is not available for the user, and you as the developer are not checking a precondition whether that API is available for the user.',
21 },
22 422: {
23 description:
24 'Sent out when the API request is accepted, but cannot be processed because the user or Auth server is in a state where it cannot satisfy the request.',
25 },
26 429: {
27 description:
28 'Sent out when rate-limits are breached for an API. You should handle this status code often, especially in functions that authenticate a user.',
29 },
30 500: {
31 description:
32 "Indicates that the Auth server's service is degraded. Most often it points to issues in your database setup such as a misbehaving trigger on a schema, function, view or other database object.",
33 },
34 501: {
35 description:
36 'Sent out when a feature is not enabled on the Auth server, and you are trying to use an API which requires it.',
37 },
38 },
39}
40
41export const ERROR_CODES: Record<ErrorCodeService, Record<string, ErrorCodeDefinition>> = {
42 auth: {
43 anonymous_provider_disabled: {
44 description: 'Anonymous sign-ins are disabled.',
45 },
46 bad_code_verifier: {
47 description:
48 'Returned from the PKCE flow where the provided code verifier does not match the expected one. Indicates a bug in the implementation of the client library.',
49 },
50 bad_json: {
51 description: 'Usually used when the HTTP body of the request is not valid JSON.',
52 },
53 bad_jwt: {
54 description: 'JWT sent in the Authorization header is not valid.',
55 },
56 bad_oauth_callback: {
57 description:
58 'OAuth callback from provider to Auth does not have all the required attributes (state). Indicates an issue with the OAuth provider or client library implementation.',
59 },
60 bad_oauth_state: {
61 description:
62 'OAuth state (data echoed back by the OAuth provider to Briven Auth) is not in the correct format. Indicates an issue with the OAuth provider integration.',
63 },
64 captcha_failed: {
65 description:
66 'CAPTCHA challenge could not be verified with the CAPTCHA provider. Check your CAPTCHA integration.',
67 },
68 conflict: {
69 description:
70 'General database conflict, such as concurrent requests on resources that should not be modified concurrently. Can often occur when you have too many session refresh requests firing off at the same time for a user. Check your app for concurrency issues, and if detected, back off exponentially.',
71 },
72 email_address_invalid: {
73 description:
74 'Example and test domains are currently not supported. Use a different email address.',
75 },
76 email_address_not_authorized: {
77 description:
78 'Email sending is not allowed for this address as your project is using the default SMTP service. Emails can only be sent to members in your Briven organization. If you want to send emails to others, set up a custom SMTP provider.',
79 references: [
80 {
81 href: 'https://supabase.com/docs/guides/auth/auth-smtp',
82 description: 'Setting up a custom SMTP provider',
83 },
84 ],
85 },
86 email_conflict_identity_not_deletable: {
87 description:
88 "Unlinking this identity causes the user's account to change to an email address which is already used by another user account. Indicates an issue where the user has two different accounts using different primary email addresses. You may need to migrate user data to one of their accounts in this case.",
89 },
90 email_exists: {
91 description: 'Email address already exists in the system.',
92 },
93 email_not_confirmed: {
94 description: 'Signing in is not allowed for this user as the email address is not confirmed.',
95 },
96 email_provider_disabled: {
97 description: 'Signups are disabled for email and password.',
98 },
99 flow_state_expired: {
100 description:
101 'PKCE flow state to which the API request relates has expired. Ask the user to sign in again.',
102 },
103 flow_state_not_found: {
104 description:
105 'PKCE flow state to which the API request relates no longer exists. Flow states expire after a while and are progressively cleaned up, which can cause this error. Retried requests can cause this error, as the previous request likely destroyed the flow state. Ask the user to sign in again.',
106 },
107 hook_payload_invalid_content_type: {
108 description: 'Payload from Auth does not have a valid Content-Type header.',
109 },
110 hook_payload_over_size_limit: {
111 description: 'Payload from Auth exceeds maximum size limit.',
112 },
113 hook_timeout: {
114 description: 'Unable to reach hook within maximum time allocated.',
115 },
116 hook_timeout_after_retry: {
117 description: 'Unable to reach hook after maximum number of retries.',
118 },
119 identity_already_exists: {
120 description: 'The identity to which the API relates is already linked to a user.',
121 },
122 identity_not_found: {
123 description:
124 'Identity to which the API call relates does not exist, such as when an identity is unlinked or deleted.',
125 },
126 insufficient_aal: {
127 description:
128 'To call this API, the user must have a higher Authenticator Assurance Level. To resolve, ask the user to solve an MFA challenge.',
129 references: [
130 {
131 href: 'https://supabase.com/docs/guides/auth/auth-mfa',
132 description: 'MFA',
133 },
134 ],
135 },
136 invite_not_found: {
137 description: 'Invite is expired or already used.',
138 },
139 invalid_credentials: {
140 description: 'Login credentials or grant type not recognized.',
141 },
142 manual_linking_disabled: {
143 description:
144 'Calling the briven.auth.linkUser() and related APIs is not enabled on the Auth server.',
145 },
146 mfa_challenge_expired: {
147 description:
148 'Responding to an MFA challenge should happen within a fixed time period. Request a new challenge when encountering this error.',
149 },
150 mfa_factor_name_conflict: {
151 description: 'MFA factors for a single user should not have the same friendly name.',
152 },
153 mfa_factor_not_found: {
154 description: 'MFA factor no longer exists.',
155 },
156 mfa_ip_address_mismatch: {
157 description:
158 'The enrollment process for MFA factors must begin and end with the same IP address.',
159 },
160 mfa_phone_enroll_not_enabled: {
161 description: 'Enrollment of MFA Phone factors is disabled.',
162 },
163 mfa_phone_verify_not_enabled: {
164 description: 'Login via Phone factors and verification of new Phone factors is disabled.',
165 },
166 mfa_totp_enroll_not_enabled: {
167 description: 'Enrollment of MFA TOTP factors is disabled.',
168 },
169 mfa_totp_verify_not_enabled: {
170 description: 'Login via TOTP factors and verification of new TOTP factors is disabled.',
171 },
172 mfa_verification_failed: {
173 description: 'MFA challenge could not be verified -- wrong TOTP code.',
174 },
175 mfa_verification_rejected: {
176 description:
177 'Further MFA verification is rejected. Only returned if the MFA verification attempt hook returns a reject decision.',
178 references: [
179 {
180 href: 'https://supabase.com/docs/guides/auth/auth-hooks?language=add-admin-role#hook-mfa-verification-attempt',
181 description: 'MFA verification hook',
182 },
183 ],
184 },
185 mfa_verified_factor_exists: {
186 description:
187 'Verified phone factor already exists for a user. Unenroll existing verified phone factor to continue.',
188 },
189 mfa_web_authn_enroll_not_enabled: {
190 description: 'Enrollment of MFA Web Authn factors is disabled.',
191 },
192 mfa_web_authn_verify_not_enabled: {
193 description:
194 'Login via WebAuthn factors and verification of new WebAuthn factors is disabled.',
195 },
196 no_authorization: {
197 description: 'This HTTP request requires an Authorization header, which is not provided.',
198 },
199 not_admin: {
200 description:
201 'User accessing the API is not admin, i.e. the JWT does not contain a role claim that identifies them as an admin of the Auth server.',
202 },
203 oauth_provider_not_supported: {
204 description: 'Using an OAuth provider which is disabled on the Auth server.',
205 },
206 otp_disabled: {
207 description:
208 "Sign in with OTPs (magic link, email OTP) is disabled. Check your server's configuration.",
209 },
210 otp_expired: {
211 description: 'OTP code for this sign-in has expired. Ask the user to sign in again.',
212 },
213 over_email_send_rate_limit: {
214 description:
215 'Too many emails have been sent to this email address. Ask the user to wait a while before trying again.',
216 },
217 over_request_rate_limit: {
218 description:
219 'Too many requests have been sent by this client (IP address). Ask the user to try again in a few minutes. Sometimes can indicate a bug in your application that mistakenly sends out too many requests (such as a badly written useEffect React hook).',
220 references: [
221 {
222 href: 'https://react.dev/reference/react/useEffect',
223 description: 'React useEffect hook',
224 },
225 ],
226 },
227 over_sms_send_rate_limit: {
228 description:
229 'Too many SMS messages have been sent to this phone number. Ask the user to wait a while before trying again.',
230 },
231 phone_exists: {
232 description: 'Phone number already exists in the system.',
233 },
234 phone_not_confirmed: {
235 description: 'Signing in is not allowed for this user as the phone number is not confirmed.',
236 },
237 phone_provider_disabled: {
238 description: 'Signups are disabled for phone and password.',
239 },
240 provider_disabled: {
241 description: "OAuth provider is disabled for use. Check your server's configuration.",
242 },
243 provider_email_needs_verification: {
244 description:
245 "Not all OAuth providers verify their user's email address. Briven Auth requires emails to be verified, so this error is sent out when a verification email is sent after completing the OAuth flow.",
246 },
247 reauthentication_needed: {
248 description:
249 'A user needs to reauthenticate to change their password. Ask the user to reauthenticate by calling the briven.auth.reauthenticate() API.',
250 },
251 reauthentication_not_valid: {
252 description:
253 'Verifying a reauthentication failed, the code is incorrect. Ask the user to enter a new code.',
254 },
255 refresh_token_not_found: {
256 description: 'Session containing the refresh token not found.',
257 },
258 refresh_token_already_used: {
259 description:
260 'Refresh token has been revoked and falls outside the refresh token reuse interval. See the documentation on sessions for further information.',
261 references: [
262 {
263 href: 'https://supabase.com/docs/guides/auth/sessions',
264 description: 'Auth sessions',
265 },
266 ],
267 },
268 request_timeout: {
269 description: 'Processing the request took too long. Retry the request.',
270 },
271 same_password: {
272 description:
273 'A user that is updating their password must use a different password than the one currently used.',
274 },
275 saml_assertion_no_email: {
276 description:
277 "SAML assertion (user information) was received after sign in, but no email address was found in it, which is required. Check the provider's attribute mapping and/or configuration.",
278 },
279 saml_assertion_no_user_id: {
280 description:
281 "SAML assertion (user information) was received after sign in, but a user ID (called NameID) was not found in it, which is required. Check the SAML identity provider's configuration.",
282 },
283 saml_entity_id_mismatch: {
284 description:
285 '(Admin API.) Updating the SAML metadata for a SAML identity provider is not possible, as the entity ID in the update does not match the entity ID in the database. This is equivalent to creating a new identity provider, and you should do that instead.',
286 },
287 saml_idp_already_exists: {
288 description: '(Admin API.) Adding a SAML identity provider that is already added.',
289 },
290 saml_idp_not_found: {
291 description:
292 'SAML identity provider not found. Most often returned after IdP-initiated sign-in with an unregistered SAML identity provider in Briven Auth.',
293 },
294 saml_metadata_fetch_failed: {
295 description:
296 '(Admin API.) Adding or updating a SAML provider failed as its metadata could not be fetched from the provided URL.',
297 },
298 saml_provider_disabled: {
299 description: 'Using Enterprise SSO with SAML 2.0 is not enabled on the Auth server.',
300 references: [
301 {
302 href: 'https://supabase.com/docs/guides/auth/enterprise-sso/auth-sso-saml',
303 description: 'Enterprise SSO',
304 },
305 ],
306 },
307 saml_relay_state_expired: {
308 description:
309 'SAML relay state is an object that tracks the progress of a briven.auth.signInWithSSO() request. The SAML identity provider should respond after a fixed amount of time, after which this error is shown. Ask the user to sign in again.',
310 },
311 saml_relay_state_not_found: {
312 description:
313 'SAML relay states are progressively cleaned up after they expire, which can cause this error. Ask the user to sign in again.',
314 },
315 session_expired: {
316 description:
317 'Session to which the API request relates has expired. This can occur if an inactivity timeout is configured, or the session entry has exceeded the configured timebox value. See the documentation on sessions for more information.',
318 references: [
319 {
320 href: 'https://supabase.com/docs/guides/auth/sessions',
321 description: 'Auth sessions',
322 },
323 ],
324 },
325 session_not_found: {
326 description:
327 'Session to which the API request relates no longer exists. This can occur if the user has signed out, or the session entry in the database was deleted in some other way.',
328 },
329 signup_disabled: {
330 description: 'Sign ups (new account creation) are disabled on the server.',
331 },
332 single_identity_not_deletable: {
333 description:
334 "Every user must have at least one identity attached to it, so deleting (unlinking) an identity is not allowed if it's the only one for the user.",
335 },
336 sms_send_failed: {
337 description: 'Sending an SMS message failed. Check your SMS provider configuration.',
338 },
339 sso_domain_already_exists: {
340 description: '(Admin API.) Only one SSO domain can be registered per SSO identity provider.',
341 },
342 sso_provider_not_found: {
343 description: 'SSO provider not found. Check the arguments in briven.auth.signInWithSSO().',
344 },
345 too_many_enrolled_mfa_factors: {
346 description: 'A user can only have a fixed number of enrolled MFA factors.',
347 },
348 unexpected_audience: {
349 description:
350 "(Deprecated feature not available via Briven client libraries.) The request's X-JWT-AUD claim does not match the JWT's audience.",
351 },
352 unexpected_failure: {
353 description: 'Auth service is degraded or a bug is present, without a specific reason.',
354 },
355 user_already_exists: {
356 description:
357 'User with this information (email address, phone number) cannot be created again as it already exists.',
358 },
359 user_banned: {
360 description:
361 'User to which the API request relates has a banned_until property which is still active. No further API requests should be attempted until this field is cleared.',
362 },
363 user_not_found: {
364 description: 'User to which the API request relates no longer exists.',
365 },
366 user_sso_managed: {
367 description:
368 'When a user comes from SSO, certain fields of the user cannot be updated (like email).',
369 },
370 validation_failed: {
371 description: 'Provided parameters are not in the expected format.',
372 },
373 weak_password: {
374 description:
375 'User is signing up or changing their password without meeting the password strength criteria. Use the AuthWeakPasswordError class to access more information about what they need to do to make the password pass.',
376 },
377 },
378 realtime: {
379 TopicNameRequired: {
380 description: 'You are trying to use Realtime without a topic name set.',
381 },
382 RealtimeDisabledForConfiguration: {
383 description:
384 'The configuration provided to Realtime on connect will not be able to provide you any Postgres Changes.',
385 resolution:
386 'Verify your configuration on channel startup as you might not have your tables properly registered.',
387 },
388 TenantNotFound: {
389 description: 'The tenant you are trying to connect to does not exist.',
390 resolution:
391 'Verify the tenant name you are trying to connect to exists in the realtime.tenants table.',
392 },
393 ErrorConnectingToWebsocket: {
394 description: 'Error when trying to connect to the WebSocket server.',
395 resolution: 'Verify user information on connect.',
396 },
397 ErrorAuthorizingWebsocket: {
398 description: 'Error when trying to authorize the WebSocket connection.',
399 resolution: 'Verify user information on connect.',
400 },
401 TableHasSpacesInName: {
402 description:
403 'The table you are trying to listen to has spaces in its name which we are unable to support.',
404 resolution: 'Change the table name to not have spaces in it.',
405 },
406 UnableToDeleteTenant: {
407 description: 'Error when trying to delete a tenant.',
408 },
409 UnableToSetPolicies: {
410 description: 'Error when setting up Authorization Policies.',
411 },
412 UnableCheckoutConnection: {
413 description: 'Error when trying to checkout a connection from the tenant pool.',
414 },
415 UnableToSubscribeToPostgres: {
416 description: 'Error when trying to subscribe to Postgres changes.',
417 },
418 ReconnectSubscribeToPostgres: {
419 description: 'Postgres changes still waiting to be subscribed.',
420 },
421 ChannelRateLimitReached: {
422 description: 'The number of channels you can create has reached its limit.',
423 },
424 ConnectionRateLimitReached: {
425 description: 'The number of connected clients has reached its limit.',
426 },
427 ClientJoinRateLimitReached: {
428 description: 'The rate of joins per second from your clients has reached the channel limits.',
429 },
430 RealtimeDisabledForTenant: {
431 description: 'Realtime has been disabled for the tenant.',
432 resolution:
433 'Your project may have been suspended for exceeding usage quotas. Contact support with your project reference ID and a description of your Realtime use case.',
434 references: [
435 {
436 href: 'https://supabase.com/docs/troubleshooting/realtime-project-suspended-for-exceeding-quotas',
437 description: 'Troubleshooting guide for suspended projects',
438 },
439 ],
440 },
441 UnableToConnectToTenantDatabase: {
442 description: "Realtime was not able to connect to the tenant's database.",
443 },
444 DatabaseLackOfConnections: {
445 description:
446 "Realtime was not able to connect to the tenant's database due to not having enough available connections.",
447 resolution: 'Verify your database connection limits.',
448 references: [
449 {
450 href: 'https://supabase.com/docs/guides/database/connection-management',
451 description: 'Connection management guide',
452 },
453 ],
454 },
455 RealtimeNodeDisconnected: {
456 description:
457 'Realtime is a distributed application and this means that one the system is unable to communicate with one of the distributed nodes.',
458 },
459 MigrationsFailedToRun: {
460 description:
461 'Error when running the migrations against the Tenant database that are required by Realtime.',
462 },
463 StartListenAndReplicationFailed: {
464 description:
465 'Error when starting the replication and listening of errors for database broadcasting.',
466 },
467 ReplicationMaxWalSendersReached: {
468 description: 'Maximum number of WAL senders reached in tenant database.',
469 references: [
470 {
471 href: 'https://supabase.com/docs/guides/database/custom-postgres-config#cli-configurable-settings',
472 description: 'Configuring max WAL senders',
473 },
474 ],
475 },
476 MigrationCheckFailed: {
477 description: 'Check to see if we require to run migrations fails.',
478 },
479 PartitionCreationFailed: {
480 description: 'Error when creating partitions for realtime.messages.',
481 },
482 ErrorStartingPostgresCDCStream: {
483 description:
484 'Error when starting the Postgres CDC stream which is used for Postgres Changes.',
485 },
486 UnknownDataProcessed: {
487 description: 'An unknown data type was processed by the Realtime system.',
488 },
489 ErrorStartingPostgresCDC: {
490 description:
491 'Error when starting the Postgres CDC extension which is used for Postgres Changes.',
492 },
493 ReplicationSlotBeingUsed: {
494 description: 'The replication slot is being used by another transaction.',
495 },
496 PoolingReplicationPreparationError: {
497 description: 'Error when preparing the replication slot.',
498 },
499 PoolingReplicationError: {
500 description: 'Error when pooling the replication slot.',
501 },
502 SubscriptionDeletionFailed: {
503 description: 'Error when trying to delete a subscription for postgres changes.',
504 },
505 UnableToDeletePhantomSubscriptions: {
506 description: 'Error when trying to delete subscriptions that are no longer being used.',
507 },
508 UnableToCheckProcessesOnRemoteNode: {
509 description: 'Error when trying to check the processes on a remote node.',
510 },
511 UnableToCreateCounter: {
512 description: 'Error when trying to create a counter to track rate limits for a tenant.',
513 },
514 UnableToIncrementCounter: {
515 description: 'Error when trying to increment a counter to track rate limits for a tenant.',
516 },
517 UnableToDecrementCounter: {
518 description: 'Error when trying to decrement a counter to track rate limits for a tenant.',
519 },
520 UnableToUpdateCounter: {
521 description: 'Error when trying to update a counter to track rate limits for a tenant.',
522 },
523 UnableToFindCounter: {
524 description: 'Error when trying to find a counter to track rate limits for a tenant.',
525 },
526 UnhandledProcessMessage: {
527 description: 'Unhandled message received by a Realtime process.',
528 },
529 UnableToTrackPresence: {
530 description: 'Error when handling track presence for this socket.',
531 },
532 UnknownPresenceEvent: {
533 description: 'Presence event type not recognized by service.',
534 },
535 IncreaseConnectionPool: {
536 description:
537 'The number of connections you have set for Realtime are not enough to handle your current use case.',
538 },
539 RlsPolicyError: {
540 description: 'Error on RLS policy used for authorization.',
541 },
542 ConnectionInitializing: {
543 description: 'Database is initializing connection.',
544 },
545 DatabaseConnectionIssue: {
546 description: 'Database had connection issues and connection was not able to be established.',
547 },
548 UnableToConnectToProject: {
549 description: 'Unable to connect to Project database.',
550 },
551 InvalidJWTExpiration: {
552 description: "JWT exp claim value it's incorrect.",
553 },
554 JwtSignatureError: {
555 description: 'JWT signature was not able to be validated.',
556 },
557 MalformedJWT: {
558 description: 'Token received does not comply with the JWT format.',
559 },
560 Unauthorized: {
561 description: 'Unauthorized access to Realtime channel.',
562 },
563 RealtimeRestarting: {
564 description: 'Realtime is currently restarting.',
565 },
566 UnableToProcessListenPayload: {
567 description: 'Payload sent in NOTIFY operation was "NOT" JSON parsable.',
568 },
569 UnableToListenToTenantDatabase: {
570 description: 'Unable to LISTEN for notifications against the Tenant Database.',
571 },
572 UnprocessableEntity: {
573 description:
574 'Received a HTTP request with a body that was not able to be processed by the endpoint.',
575 },
576 InitializingProjectConnection: {
577 description: 'Connection against Tenant database is still starting.',
578 },
579 TimeoutOnRpcCall: {
580 description: 'RPC request within the Realtime server has timed out.',
581 },
582 ErrorOnRpcCall: {
583 description: 'Error when calling another realtime node.',
584 },
585 ErrorExecutingTransaction: {
586 description: 'Error executing a database transaction in tenant database.',
587 },
588 SynInitializationError: {
589 description:
590 'Our framework to syncronize processes has failed to properly startup a connection to the database.',
591 },
592 JanitorFailedToDeleteOldMessages: {
593 description: 'Scheduled task for realtime.message cleanup was unable to run.',
594 },
595 UnableToEncodeJson: {
596 description:
597 'An error were we are not handling correctly the response to be sent to the end user.',
598 },
599 UnknownErrorOnController: {
600 description: 'An error we are not handling correctly was triggered on a controller.',
601 },
602 UnknownErrorOnChannel: {
603 description: 'An error we are not handling correctly was triggered on a channel.',
604 },
605 },
606}