{"record":{"id":"25e41b5ad9d77b66","repo":"mastra-ai/mastra","slug":"better-auth-instance-is-required-please-provide-t","errorCode":null,"errorMessage":"Better Auth instance is required. Please provide the auth option with your Better Auth instance created via betterAuth({ ... }), or provide `secret` so the provider can build its own instance in init() on the host database.","messagePattern":"Better Auth instance is required\\. Please provide the auth option with your Better Auth instance created via betterAuth\\((.+?)\\), or provide `secret` so the provider can build its own instance in init\\(\\) on the host database\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"auth/better-auth/src/index.ts","lineNumber":214,"sourceCode":"      this.#orgCache.delete(key);\n    }\n    this.#orgCache.delete(userId);\n    this.#orgCache.set(userId, { orgId, expiresAt: now + ORG_CACHE_TTL_MS });\n  }\n\n  /** @internal Test hook: current org-cache cardinality. */\n  get orgCacheSize(): number {\n    return this.#orgCache.size;\n  }\n  /** Set from `init()`: cross-origin SPA deploys need SameSite=None; Secure cookies. */\n  #crossSite = false;\n  protected signUpEnabledConfig: boolean;\n\n  constructor(options: MastraAuthBetterAuthOptions) {\n    super({ name: options?.name ?? 'better-auth' });\n\n    if (!options.auth && !options.secret) {\n      throw new Error(\n        'Better Auth instance is required. Please provide the auth option with your Better Auth instance created via betterAuth({ ... }), ' +\n          'or provide `secret` so the provider can build its own instance in init() on the host database.',\n      );\n    }\n\n    this.#auth = options.auth;\n    this.#secret = options.secret;\n    this.signUpEnabledConfig = options.signUpEnabled ?? true;\n\n    this.registerOptions(options);\n  }\n\n  /**\n   * The active Better Auth instance. Throws before `init()` in deferred\n   * instance mode (constructed with `secret` instead of `auth`).\n   */\n  protected get auth(): Auth {\n    if (!this.#auth) {","sourceCodeStart":196,"sourceCodeEnd":232,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/auth/better-auth/src/index.ts#L196-L232","documentation":"MastraAuthBetterAuth can run in two modes: bring-your-own Better Auth instance (options.auth) or deferred mode where init() builds an instance on the host database using options.secret. The constructor throws if neither is provided, because without one of them the provider has no way to create or reach a Better Auth backend.","triggerScenarios":"new MastraAuthBetterAuth({}) or options missing both auth and secret: `if (!options.auth && !options.secret) throw` in the constructor.","commonSituations":"Migrating from another auth provider and forgetting to pass the betterAuth() instance; reading config from env vars that are undefined at startup (e.g. BETTER_AUTH_SECRET unset); constructing the provider before async env/config loading completes.","solutions":["Pass your existing Better Auth instance: new MastraAuthBetterAuth({ auth: betterAuth({...}) }).","Or pass a secret so init() builds the instance on the host database: new MastraAuthBetterAuth({ secret: process.env.BETTER_AUTH_SECRET }).","If using env vars, verify they are loaded (e.g. dotenv/config import order) before constructing the provider."],"exampleFix":"// before\nconst auth = new MastraAuthBetterAuth({ name: 'better-auth' });\n\n// after\nimport { betterAuth } from 'better-auth';\nconst auth = new MastraAuthBetterAuth({\n  auth: betterAuth({ database: myDb, secret: process.env.BETTER_AUTH_SECRET }),\n});\n// or: new MastraAuthBetterAuth({ secret: process.env.BETTER_AUTH_SECRET })","handlingStrategy":"validation","validationCode":"const options = { auth: maybeAuthInstance, secret: process.env.BETTER_AUTH_SECRET };\nif (!options.auth && !options.secret) {\n  throw new Error('Provide either a betterAuth({ ... }) instance or a secret before constructing MastraAuthBetterAuth');\n}\nconst provider = new MastraAuthBetterAuth(options);","typeGuard":"function hasBetterAuthConfig(o: Partial<MastraAuthBetterAuthOptions>): o is MastraAuthBetterAuthOptions & ({ auth: Auth } | { secret: string }) {\n  return Boolean(o.auth) || typeof o.secret === 'string' && o.secret.length > 0;\n}","tryCatchPattern":"let provider;\ntry {\n  provider = new MastraAuthBetterAuth(options);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('Better Auth instance is required')) {\n    throw new Error('Misconfiguration: set BETTER_AUTH_SECRET or pass auth: betterAuth({...})', { cause: e });\n  }\n  throw e;\n}","preventionTips":["Always pass either auth or secret explicitly rather than relying on optional chaining defaults.","Validate env vars (BETTER_AUTH_SECRET) at startup with a schema validator (zod/envschema).","Centralize provider construction in one config module so the requirement is enforced once."],"tags":["configuration","better-auth","missing-option","constructor"],"backgroundTag":"missing-required-option","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}