payloadcms/payload · error

Unauthorized

Error message

Unauthorized

What it means

A plain Error('Unauthorized') thrown by the TanStack Start server adapter's unauthorized() helper. TanStack Router lacks a dedicated unauthorized primitive, so the adapter throws a generic error when framework code calls adapter.unauthorized() — typically because no user was resolved during an admin page render.

Source

Thrown at packages/tanstack-start/src/utilities/serverAdapter.server.ts:99

  },

  permanentRedirect: (path: string) => {
    // TanStack Router does not have a separate permanent redirect primitive;
    // fall back to a regular redirect so existing behavior is preserved.
    // eslint-disable-next-line @typescript-eslint/only-throw-error
    throw redirect({ to: path })
  },

  forbidden: () => {
    // TanStack Router does not have a dedicated forbidden() helper; surface
    // a generic error so the request boundary still terminates the request.
    throw new Error('Forbidden')
  },

  unauthorized: () => {
    // TanStack Router does not have a dedicated unauthorized() helper; surface
    // a generic error so the request boundary still terminates the request.
    throw new Error('Unauthorized')
  },

  setCookie: (name: string, value: string, options?: CookieOptions) => {
    setResponseHeader('Set-Cookie', serializeCookie(name, value, options))
  },
}

/**
 * Navigation requested during an admin page render, recorded by
 * `createPageRenderServerAdapter`. The admin-page server function reads this
 * after `renderServerComponent` resolves.
 */
export type PageNavIntent = {
  type?: 'notFound' | 'redirect'
  url?: string
}

/**

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Ensure the session cookie is sent and parsed before the guarded route renders.
2. Configure the auth strategy so req.user is populated for the TanStack Start adapter.
3. Handle this generic error in the error boundary to redirect to login / render a 401 page.

Example fix

// before
unauthorized: () => {
  throw new Error('Unauthorized')
},

// after
import { UnauthorizedError } from 'payload'
unauthorized: () => {
  throw new UnauthorizedError()
},

function isAuthenticated(user: unknown): user is { id: string } {
  return Boolean(user)
}

if (!isAuthenticated(req.user)) {
  // handle before the adapter calls unauthorized()
  redirect('/login')
}

function isAdapterUnauthorized(err: unknown): err is Error {
  return err instanceof Error && err.message === 'Unauthorized'
}

try {
  await renderAdminPage()
} catch (err) {
  if (isAdapterUnauthorized(err)) {
    redirectToLogin()
    return
  }
  throw err
}

When it happens

Trigger: The admin page-render pipeline calls adapter.unauthorized() because req.user is null during a TanStack Start server render (no session, expired session, or auth not yet resolved).

Common situations: Reaching a guarded admin route without a session cookie; session expired between requests; auth strategy not wired into the TanStack Start adapter; SSR happening before cookie parsing.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Forbidden
• Unauthorized
• Unauthorized, you must be logged in to make this request.
• Unauthorized, you must be logged in to make this request.
• Unauthorized

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/4bf4a0ef1d750fde. Report an issue: GitHub.