supabase-errors

An error handling library for the Supabase JS and GoTrue JS auth clients.

The GoTrue API, which is also used by Supabase, does not return unique error codes. It does, however, return a descriptive error message. This package maps these error messages to more usable unique error codes. There is an error handler for every JS client function that calls the API.

Quick start

Install

npm install supabase-errors
// or
yarn add supabase-errors

Usage

import { ErrorHandler, type SignInWithPasswordErrorCode  } from 'supabase-errors';

const { data, error } = await supabase.auth.signInWithPassword({...});

const handler = new ErrorHandler({combineInternalErrors: true, exludeErrorTypes: ['TypeScriptSafe']});

// Implement error handlers
handler.handleSignInWithPasswordError(error, {
    onEmailLoginDisabled: () => console.log('Email logins are disabled'),
    onInternalError: (errorCode) => console.log('Internal error: ', errorCode),
    onUnhandledError: (errorCode) => console.log('Unhandled error code: ', errorCode),
    onUnknownError: (error) => console.log('Unhandled auth error: ', error), 
});

// Create error mappings
const signInWithPasswordErrorMessageMap: Record<SignInWithPasswordErrorCode, string>  = {
  'email-login-disabled': 'Email logins are not supported',
}

Documentation

Config

| Parameter | Options | Default | Description | |-----------|---------|---------|-------------| combineInternalErrors | boolean | false | Removes all handlers of '5XX' errors and combines them in a handler called onInternalError. | | excludeErrorTypes | ErrorType[] | [] | Removes all handlers of errors that match one of the excluded types. | | disableLogging | boolean | false | Controls whether unknown errors are logged.

Error types

| Type | Description | |------|-------------| | 4XX | Bad request errors | 5XX | Internal errors | TypeScriptSafe | Errors that can not occur when the Typescript version of the Supabase or GoTrue client is used. For example, the 'only-email-or-phone-number' error can never occur when your code is type-safe.

Coverage

This package is currently work in progress. Below is a list of all functions needing an error handler and their current development status.

| Status | Description | |--------|-------------| | | Can handle the complete list of erros | | | Can handle the complete list of bad request errors | | | Can handle some errors | | | Only onUnknownError is implemented |

Errors that occur due to a misconfiguration, e.g. an invalid webhook URL, are currently not included in the full coverage.

Error handlers

| Method | Status | |--------|--------| | signup | | | signinWithPassword | | | signInWithOtp | | | signInWithOAuth | | | signInWithSSO | | | signOut | | | resetPasswordForEmail | | | verifyOtp | | | getSession | | | refreshSession | | | getUser | | | updateUser | | | reauthenticate | | | resend | | | setSession | | | exchangeCodeForSession | | | getUserById | | | listUsers | | | createUser | | | deleteUser | | | inviteUserByEmail | | | generateLink | | | updateUserById | |