BUG - handlers with AllowAnonymous decorator still use better-auth getSession and hit DB connection

[JSteunou]

Use case: I have liveness / readyness endpoints and those check the DB connection among other things. Those endpoints are anonymous.

Issue : error for DB connection failure rise before I can do my check with my logic with my error handling, error code, msg because AuthGuard.canActivate calls getSession() before checking on AllowAnonymous . isPublic is never reached.

[ropdias]

Hi there, thanks for opening this issue.

Your use case makes perfect sense—health check endpoints (liveness/readiness probes) must remain resilient and decouple their execution from database availability, so an auth guard shouldn't be blocking them when the DB is down.

To help us pinpoint why the AuthGuard is eagerly invoking getSession() before the metadata for AllowAnonymous is evaluated, could you share a bit more technical context? Specifically:

• Guard Configuration: Are you using the default setup (where the guard is registered globally by the module), or have you set disableGlobalAuthGuard: true and applied @UseGuards(AuthGuard) manually at the controller/route level?
• Better Auth Configuration: A minimal version of your Better Auth initialization file (e.g., your auth.ts where you call betterAuth({ ... })). Please make sure to redact any sensitive credentials or secrets. We just need to check the database adapter setup and which plugins are active, as some plugins or hooks can affect the request lifecycle execution order.
• Controller Snippet: A minimal snippet showing how your health check controller and the @AllowAnonymous() decorator are declared.
• Stack Trace: The full error log/stack trace when the DB connection failure occurs. This will help us confirm exactly where getSession() is being triggered in the request lifecycle.
• Environment Details: The exact versions of nestjs-better-auth, @nestjs/core, and better-auth you are currently running.

This will help us determine if this is a metadata reflection sorting issue within canActivate or an execution order quirk in the request pipeline. Looking forward to your reply so we can get this sorted out!

[JSteunou]

Hi @ropdias, thanks for the quick and detailed response!

disclaimer: response generated with the help of Claude Sonnet (with my control and validation)

---

Here are all the elements you asked for.

---

1. Guard configuration

Default setup — the module registers the guard globally. That's precisely where the bug manifests.

// app.module.ts
BetterAuthModule.forRootAsync({
  imports: [ConfigModule, DbModule],
  inject: [CONFIG, DRIZZLE],
  useFactory: (config, db) => ({
    auth: betterAuth({
      database: drizzleAdapter(db, { provider: 'pg', schema }),
      // ...plugins
    }),
  }),
}),

---

2. Controller snippet

@Controller('health')
@AllowAnonymous()
export class HealthController {
  constructor(@Inject(DRIZZLE) private readonly db: DBClient) {}

  @Get('live')
  live() {
    return { status: 'ok' }
  }

  @Get('ready')
  async ready() {
    // does a SELECT 1 with timeout, returns 503 if DB is down
    const result = await checkDb({ db: this.db, timeoutMs: 5000 })
    if (result.status === 'down') {
      throw new HttpException({ status: 'error' }, HttpStatus.SERVICE_UNAVAILABLE)
    }
    return { status: 'ok' }
  }
}

---

3. Root cause — confirmed by reading the compiled source

I confirmed the issue by reading dist/index.mjs of @thallesp/nestjs-better-auth@2.6.1:

async canActivate(context) {
  const request = await getRequestFromContext(context);
  // ↓ getSession() is called UNCONDITIONALLY, before any metadata check
  const session = await this.options.auth.api.getSession({
    headers: fromNodeHeaders(request.headers || ...)
  });
  request.session = session;
  request.user = session?.user ?? null;

  // ↓ isPublic is only read AFTER the DB round-trip
  const isPublic = this.reflector.getAllAndOverride("PUBLIC", [
    context.getHandler(),
    context.getClass()
  ]);
  if (isPublic) return true;
  // ...
}

When the DB is down, getSession() throws (better-auth uses the same DB connection), and isPublic is never reached. The result is a 500 {"statusCode":500,"message":"Failed to get session"} on every @AllowAnonymous() route.

This is particularly painful for k8s readiness probes: the probe's job is to detect a DB outage, but the auth guard kills the request before the probe logic even runs.

---

4. Environment

Package	Version
@thallesp/nestjs-better-auth	2.6.1
better-auth	1.6.22
@nestjs/core	11.1.27

---

5. Workaround we implemented

We disabled the built-in global guard and replaced it with a wrapper that checks isPublic first:

// safe-auth.guard.ts
@Injectable()
export class SafeAuthGuard implements CanActivate {
  private readonly innerGuard: AuthGuard

  constructor(
    private readonly reflector: Reflector,
    authService: AuthService, // exported by BetterAuthModule
  ) {
    // Note: AUTH_MODULE_OPTIONS_KEY is NOT re-exported, AuthService.instance is the way to go
    this.innerGuard = new AuthGuard(reflector, { auth: authService.instance })
  }

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const isPublic = this.reflector.getAllAndOverride<boolean>('PUBLIC', [
      context.getHandler(),
      context.getClass(),
    ])
    if (isPublic) return true // short-circuit before any DB call
    return this.innerGuard.canActivate(context)
  }
}

// app.module.ts
BetterAuthModule.forRootAsync({
  // ...
  disableGlobalAuthGuard: true, // must be here (static option), NOT in useFactory return
}),
providers: [
  { provide: APP_GUARD, useClass: SafeAuthGuard },
],

One gotcha we hit: disableGlobalAuthGuard: true must be placed in the forRootAsync static options object, not in the object returned by useFactory. The ConfigurableModuleBuilder reads extras at module definition time — putting it in the factory return value silently has no effect and the original guard stays registered, causing both guards to run.

---

The fix in the library itself would be to swap the two lines in canActivate: read isPublic from the reflector first, and only call getSession() if the route is not public. Happy to open a PR if that's useful.

---

[JSteunou]

I would go further :

• I think the fix could be breaking because some might use public route whereas still consume session in it (I think that is a bad practice but why not... In theory it would be possible)
• If you want to absolute maintain the actual behavior (session available even in public routes) but still fixing the issue it would require a bit more change
  1. make a helper to get / set the session
  2. use it inside if (isPublic) block with a double check on a new option like injectSessionInPublicRoutes, which should be true by default to preserve behavior `
  3. after the end of the isPublic block, call unconditionally the session helper to get / set it for good.

---

6. Proposed fix in the library

A naïve fix — read isPublic first and skip getSession() entirely on public routes — would be a breaking change: some consumers annotate a route @AllowAnonymous() while still reading request.session when it happens to be present (optional-auth pattern). Skipping getSession() would silently drop the session for those routes.

A non-breaking fix introduces a new option and extracts a helper:

Step 1 — extract a getAndSetSession helper

private async getAndSetSession(request: Request): Promise<Session | null> {
  const session = await this.options.auth.api.getSession({
    headers: fromNodeHeaders(request.headers || request?.handshake?.headers || []),
  })
  request.session = session
  request.user = session?.user ?? null
  return session
}

Step 2 — check isPublic first, then branch on the new option

async canActivate(context: ExecutionContext): Promise<boolean> {
  const request = await getRequestFromContext(context)

  const isPublic = this.reflector.getAllAndOverride('PUBLIC', [
    context.getHandler(),
    context.getClass(),
  ])

  if (isPublic) {
    if (this.options.injectSessionInPublicRoutes !== false) {
      await this.getAndSetSession(request)
    }
    return true
  }

  // protected route: session is required, errors propagate as before
  const session = await this.getAndSetSession(request)

  // ... rest of existing logic (isOptional, roles check, etc.)
}

What this changes:

• injectSessionInPublicRoutes: true (default) — behavior is identical to today: getSession() runs on public routes, errors propagate.
• injectSessionInPublicRoutes: false — getSession() is skipped entirely on public routes. This is the opt-in for consumers who need DB-resilient routes (health probes, unauthenticated webhooks, etc.).

Our workaround (SafeAuthGuard) solves the immediate problem on our end, but this option would let us remove that wrapper and express the intent declaratively in the module config.

Happy to open a PR if that helps.

---

[ropdias]

Thanks for the incredibly thorough follow-up, @JSteunou — the compiled-source root cause, the environment table, the workaround and the two fix proposals made this trivial to act on. 🙏

You nailed the root cause: getSession() runs before the @AllowAnonymous() / @OptionalAuth() metadata is evaluated, and since Better Auth's getSession() goes through the same DB adapter, a database outage makes it reject and NestJS turns that into a 500 on every route — the isPublic short-circuit is never reached.

On the two fixes you proposed, a couple of notes on why I went a slightly different route:

Short-circuit (read isPublic first, return true before getSession()) — breaking change, as you also flagged. The guard currently hydrates request.session / request.user before the isPublic check, so an authenticated user hitting a public route still gets req.user. Returning early would silently drop the session on public/optional routes and break the @Session() / optional-auth pattern.

A new injectSessionInPublicRoutes option — this works, but it frames things as a choice between "hydrate the session on public routes" and "DB-resilient public routes", when you can actually have both. It also adds config surface that has to be documented, tested and can be misconfigured (you already hit one such gotcha with disableGlobalAuthGuard's placement).

The fix I went with keeps a single behavior and no new option: wrap getSession() in a try/catch, fall back to a null session on failure, and let the route metadata decide. It also mirrors the try/catch + console.error pattern already used by the role/permission checks in the same guard:

let session: UserSession | null = null;
let sessionError: unknown = null;
try {
  session = await this.options.auth.api.getSession({ headers: /* ... */ });
} catch (error) {
  sessionError = error;
  console.error("Failed to retrieve session:", error);
}

request.session = session;
request.user = session?.user ?? null;

// ...reflector reads for isPublic / isOptional omitted for brevity...

if (isPublic) return true;                 // public: always through (session still hydrated when DB is up)
if (!session && isOptional) return true;   // optional: through as anonymous

// route requires a session:
if (sessionError) throw sessionError;      // real DB outage -> surface it (5xx), don't mask it as 401
if (!session) throw UNAUTHORIZED();         // no cookie -> 401, unchanged

The one deliberate difference from "just null everything out": on a protected route I re-throw the original error instead of turning it into a 401. A DB outage is a server problem (5xx), not "your credentials are wrong" — a 401 there would push SPA clients into a logout / redirect-to-login loop they can't escape while the DB is down (login needs the DB too). Public/optional routes still pass, so your readiness probe reaches its own checkDb() and returns its own 503. No API change, so it's a patch.

Opened #160 with this fix plus an e2e test (Express + Fastify) covering all three cases (@AllowAnonymous() → 200, @OptionalAuth() → 200 anonymous, protected → 500). Tagging @ThallesP for review before merge. Thanks again for the excellent write-up — your SafeAuthGuard workaround is a solid stopgap in the meantime!

[JSteunou]

I like your solution, this is very solid and as you said it has the minimal impact whereas respects the actual patterns 👏

[ThallesP]

I see the issue here, but I do not really agree with @AllowAnonymous() bypassing auth when an error happens. To me, anonymous means the session is not required, but if checking the session fails, that should still be returned as an error.

I do agree with @Public() being different. A truly public route should probably not call auth at all.

The tricky part is that users may already be using public or anonymous routes while still checking if a session exists, so changing that behavior now might be breaking.

So I am a bit torn here. Maybe this makes more sense as a v3 change, where @Public() means skip auth completely, and @AllowAnonymous() remains as is.

cc @ropdias @JSteunou

[ropdias]

Hi @ThallesP, thanks for the thoughtful concern. I think there's a key semantic distinction we should clarify here.

The Core Misunderstanding

Your concern is that @AllowAnonymous() should still return an error if getSession() fails. But I'd argue that @AllowAnonymous() already means "this route works regardless of authentication status" — and that includes when we can't validate authentication due to infrastructure failure.

Let me break down the difference:

Scenario 1: No Session at All (Current Behavior ✓)

@Get('posts')
@AllowAnonymous()
getPosts() {
  return { posts: [...] };
}

// User hits route without auth headers
// ✓ getSession() returns null (no session)
// ✓ @AllowAnonymous() is true → route passes
// ✓ This works today, no changes needed

Scenario 2: DB Down (The Problem We're Fixing ❌→✓)

@Controller('health')
@AllowAnonymous()
export class HealthController {
  @Get('ready')
  async ready() {
    const dbStatus = await checkDb();  // ← Should detect the problem
    if (!dbStatus.ok) return 503;
  }
}

// BEFORE (current code):
// 1. K8s calls GET /health/ready
// 2. AuthGuard intercepts, calls getSession()
// 3. DB is down → getSession() throws BEFORE @AllowAnonymous() is even checked
// 4. K8s receives 500 "Failed to get session"
// 5. ❌ K8s can't tell if it's "DB down" or "app broken"
// 6. ❌ The health check logic never runs

// AFTER (with the fix):
// 1. K8s calls GET /health/ready
// 2. AuthGuard intercepts, tries getSession(), captures the error
// 3. Logs the error (observability maintained ✓)
// 4. Checks @AllowAnonymous() → it's true
// 5. Route passes → handler runs
// 6. checkDb() detects the real problem
// 7. K8s receives 503 "DB is down"
// 8. ✓ K8s knows exactly what happened and can act

Why This Isn't a "Bypass"

The fix doesn't change the semantics of @AllowAnonymous() — it fixes a bug in the execution order:

// Before: auth guard checks if getSession() succeeds first, then checks @AllowAnonymous()
❌ Infrastructure error → 500 (route never gets to check its decorator)

// After: auth guard still tries getSession(), but respects @AllowAnonymous() even if it fails
✓ Infrastructure error is logged, decorator is respected, route runs its own logic

When the DB is healthy, nothing changes:

• getSession() still runs and succeeds
• request.session and request.user are fully populated
• @Session() on public routes still works
• All auth validation happens as before

The Real Semantic Question

Your suggestion to split @Public() (skip auth completely) from @AllowAnonymous() (try to validate but don't require) is great and makes sense for v3. But for v2, we have a practical problem:

What does @AllowAnonymous() mean when the auth infrastructure fails?

Option A (your concern): "Return an error — the infrastructure failed"

• ❌ But then @AllowAnonymous() doesn't really mean "anonymous is allowed"
• ❌ It means "anonymous is allowed only if auth infrastructure is healthy"
• ❌ Health checks that are supposed to detect infrastructure problems now can't run

Option B (this fix): "Route still passes — session was never required anyway"

• ✓ @AllowAnonymous() actually means "doesn't depend on auth"
• ✓ Health checks can detect their own infrastructure problems
• ✓ Error is still logged for monitoring
• ✓ Protected routes still get 5xx (not masked as 401)

Protected Routes Still Surface Errors

On routes that do require a session, we re-throw the original error as a 5xx:

if (sessionError) throw sessionError;  // real DB outage → 500, not 401

This is important: a 401 would push SPA clients into a redirect-to-login loop they can't escape while the DB is down. A 500 is the correct signal.

---

I understand the semantic concern, and I think your v3 split is a great direction. For v2, though, this fix solves a real production pain point (health checks being blocked by auth infrastructure) while maintaining backward compatibility and observability.

See #160 for the implementation, which includes e2e tests for all three cases:

• @AllowAnonymous() → 200 (route passes)
• @OptionalAuth() → 200 as anonymous (route passes)
• Protected route → 500 (error surfaced, not masked)

What do you think — does the semantic distinction land?

[JSteunou]

Could not say better.

The goal here is to fix a real issue, not evolve the current behavior.

Discussion were open on that, but the choice was made to be the less impacting possible and @ropdias succeed on that.

Another issue should be open to discuss on possible behavior changes for next major version if you want.