// Errors

Every error from Session kit's own logic is an AuthError, whether a method throws it, rejects with it, or publishes it in state.error. This page shows how to match on them, how to turn them into messages for your users, and the storage failures you need to handle.

Error codesCopy Anchor Link

Match on an error's code, not its message, which may change in any release. Error codes lists every code and what it means.

Show errors to usersCopy Anchor Link

An error's cause holds whatever failed underneath, such as the error your refresh callback threw. To keep messages out of your components, map codes to your own wording:

import { AuthError, type AuthErrorCode } from "@monarcode/session-kit";

const messages: Partial<Record<AuthErrorCode, string>> = {
  REFRESH_FAILED: "We can't reach the server. Check your connection.",
  PERSISTENCE_FAILED: "We couldn't save or clear your session.",
  UNAUTHENTICATED: "Sign in to continue.",
};

export function errorMessage(error: unknown): string {
  if (error instanceof AuthError) return messages[error.code] ?? error.message;
  return error instanceof Error ? error.message : "Something went wrong";
}

authFetch passes on the failures of fetch and Request, such as a network error, unchanged. With server rendering, the browser client's signIn passes on what your sign-in function threw, unchanged too. These usually aren't AuthErrors, so errorMessage shows their own message.

Handle storage failuresCopy Anchor Link

Three storage failures need a decision from you:

• Storage can't be read. status becomes unavailable, with the error in state.error. The saved session stays as it is, and the next getSession() or retry() reads it again.
• Storage can't be written. The client ends the session and publishes the error. That way, no one stays signed in to a session that would vanish on reload.
• Storage can't be cleared. Sign-out still takes effect in this tab, but signOut() rejects and state.error keeps the error. The saved credentials could restore the session on reload, so call signOut() again once storage works.