{"record":{"id":"fa1d7a5236634fbe","repo":"honojs/hono","slug":"basic-auth-middleware-requires-options-for-userna","errorCode":null,"errorMessage":"basic auth middleware requires options for \"username and password\" or \"verifyUser\"","messagePattern":"basic auth middleware requires options for \"username and password\" or \"verifyUser\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/middleware/basic-auth/index.ts","lineNumber":88,"sourceCode":" *     username: 'hono',\n *     password: 'ahotproject',\n *     onAuthSuccess: (c, username) => {\n *       c.set('user', { name: username, role: 'admin' })\n *       console.log(`User ${username} authenticated`)\n *     },\n *   })\n * )\n * ```\n */\nexport const basicAuth = (\n  options: BasicAuthOptions,\n  ...users: { username: string; password: string }[]\n): MiddlewareHandler => {\n  const usernamePasswordInOptions = 'username' in options && 'password' in options\n  const verifyUserInOptions = 'verifyUser' in options\n\n  if (!(usernamePasswordInOptions || verifyUserInOptions)) {\n    throw new Error(\n      'basic auth middleware requires options for \"username and password\" or \"verifyUser\"'\n    )\n  }\n\n  if (!options.realm) {\n    options.realm = 'Secure Area'\n  }\n\n  if (!options.invalidUserMessage) {\n    options.invalidUserMessage = 'Unauthorized'\n  }\n\n  if (usernamePasswordInOptions) {\n    users.unshift({ username: options.username, password: options.password })\n  }\n\n  return async function basicAuth(ctx, next) {\n    const requestUser = auth(ctx.req.raw)","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/honojs/hono/blob/e2740d5a1bd0b4254e517e3af8b60789284bc7bd/src/middleware/basic-auth/index.ts#L70-L106","documentation":"This error is thrown synchronously by Hono's basicAuth() middleware factory at creation time when the options object contains neither a username/password pair nor a verifyUser function. The middleware needs at least one way to decide which credentials are valid, so it refuses to build the handler. It is a configuration/programming error, not a runtime request error.","triggerScenarios":"Calling basicAuth({ realm: 'Secure' }) with no auth criteria; passing only username without password (e.g. basicAuth({ username: 'admin' })); passing only password; misspelling options like basicAuth({ users: [...] }) without verifyUser; passing an empty options object basicAuth({}).","commonSituations":"Typos in option names (user instead of username), copying an example that relies on verifyUser but forgetting to include the function, refactoring from a single user to a user list and dropping the credentials, or conditionally building options where both branches omit the auth fields.","solutions":["Add a static credential pair: basicAuth({ username: 'admin', password: 'secret' })","Or supply an async verifier: basicAuth({ verifyUser: async (user, pass) => ... })","If you meant multiple users, keep username/password set or implement verifyUser that checks a user store","Double-check option spelling — both 'username' AND 'password' must be present for the static path"],"exampleFix":"// before\napp.use('/admin/*', basicAuth({ realm: 'Admin' }))\n\n// after\napp.use('/admin/*', basicAuth({\n  realm: 'Admin',\n  username: 'admin',\n  password: process.env.ADMIN_PASSWORD!,\n}))","handlingStrategy":"validation","validationCode":"import { basicAuth } from 'hono/basic-auth'\nconst isValidBasicAuthOptions = (o: Record<string, unknown>): boolean =>\n  (('username' in o && 'password' in o) || 'verifyUser' in o)\n\nif (!isValidBasicAuthOptions(options)) {\n  throw new Error('basicAuth needs username+password or verifyUser')\n}\nconst middleware = basicAuth(options as any)","typeGuard":"type BasicAuthUserPass = { username: string; password: string }\ntype BasicAuthVerify = { verifyUser: (u: string, p: string, c: Context) => boolean | Promise<boolean> }\ntype ValidBasicAuthOptions = BasicAuthUserPass | BasicAuthVerify\nconst hasValidBasicAuth = (o: Partial<BasicAuthUserPass & BasicAuthVerify>): o is ValidBasicAuthOptions =>\n  (o.username !== undefined && o.password !== undefined) || typeof o.verifyUser === 'function'","tryCatchPattern":null,"preventionTips":["Type your options object as the union the middleware expects so TypeScript flags missing fields before runtime","Validate config-derived options at startup with a fail-fast check","Write a smoke test that constructs all middleware used by the app"],"tags":["basic-auth","middleware","configuration","hono","startup-error"],"backgroundTag":"middleware-misconfiguration","analyzedSha":"e2740d5a1bd0b4254e517e3af8b60789284bc7bd","analyzedAt":"2026-08-28T10:18:08.750Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}