honojs/hono · error · Error

bearer auth middleware requires options for "token" or "veri

Error message

bearer auth middleware requires options for "token" or "verifyToken"

What it means

This error is thrown synchronously by bearerAuth() at middleware-creation time when the options object contains neither a static token nor a verifyToken function. The middleware needs one of these to decide which bearer tokens are valid, so it refuses to construct the handler. It is a configuration error that surfaces when your app builds its middleware chain, before any request is served.

Source

Thrown at src/middleware/bearer-auth/index.ts:108

 *
 * @example
 * ```ts
 * const app = new Hono()
 *
 * const token = 'honoishot'
 *
 * app.use('/api/*', bearerAuth({ token }))
 *
 * app.get('/api/page', (c) => {
 *   return c.json({ message: 'You are authorized' })
 * })
 * ```
 */
export const bearerAuth = <E extends Env = Env>(
  options: BearerAuthOptions<E>
): MiddlewareHandler<E> => {
  if (!('token' in options || 'verifyToken' in options)) {
    throw new Error('bearer auth middleware requires options for "token" or "verifyToken"')
  }
  if (!options.realm) {
    options.realm = ''
  }
  if (options.prefix === undefined) {
    options.prefix = PREFIX
  }

  const realm = options.realm?.replace(/"/g, '\\"')
  const prefix = options.prefix
  const tokenRegexp = new RegExp(`^${TOKEN_STRINGS}$`)
  const wwwAuthenticatePrefix = prefix === '' ? '' : `${prefix} `

  const throwHTTPException = async (
    c: Context,
    status: ContentfulStatusCode,
    wwwAuthenticateHeader: string | object | MessageFunction,
    messageOption: string | object | MessageFunction

View on GitHub (pinned to e2740d5a1b)

Solutions

1. Pass a static token: bearerAuth({ token: process.env.API_TOKEN! })
2. Or pass a verifier for dynamic/multi-token checks: bearerAuth({ verifyToken: async (token) => tokens.includes(token) })
3. Ensure env vars are loaded before middleware construction and are non-empty
4. Check option spelling: it is exactly 'token' (string) or 'verifyToken' (function)

Example fix

// before
app.use('/api/*', bearerAuth({ realm: 'api' }))

// after
app.use('/api/*', bearerAuth({
  verifyToken: async (token) => token === process.env.API_TOKEN,
}))

const hasBearerAuthCriteria = (o: Record<string, unknown>): boolean =>
  'token' in o || 'verifyToken' in o

if (!process.env.API_TOKEN) throw new Error('API_TOKEN missing')
const middleware = bearerAuth(hasBearerAuthCriteria(opts) ? opts : { token: process.env.API_TOKEN })

type BearerAuthStatic = { token: string }
type BearerAuthDynamic = { verifyToken: (t: string, c: Context) => boolean | Promise<boolean> }
const hasBearerCriteria = (
  o: Partial<BearerAuthStatic & BearerAuthDynamic>
): o is BearerAuthStatic | BearerAuthDynamic =>
  typeof o.token === 'string' || typeof o.verifyToken === 'function'

When it happens

Trigger: Calling bearerAuth({ realm: 'api' }) with no token; passing only part of the config like bearerAuth({ prefix: 'Token' }); misspelling the option (tokens: [...] instead of token or verifyToken); conditionally spreading options where the token branch is falsy so the key is absent.

Common situations: Copy-pasting an example without filling in the token, intending multi-token support but the API only accepts a single token string (use verifyToken for lists), reading the token from an env var that is undefined and destructuring it away, or refactoring config so verifyToken gets renamed.

Related errors

• basic auth middleware requires options for "username and pas
• Context is not finalized. Did you forget to return a Respons
• Middleware vary configuration cannot include "*", as it disa
• Invalid rule: ${rule}
• JWK auth middleware requires options for either "keys" or "j

AI-assisted analysis of honojs/hono@e2740d5a1b (2026-08-28). Data as JSON: /api/errors/ce9b4e0d1be5570c. Report an issue: GitHub.