Your Next.js health check is lying to you (and how to fix it)

ependency Coverage | Platform Compliance | |----------|-------------------|---------------------|----------------|---------------------|---------------------| | Shallow 200 (Traditional) | 41+ mins (customer-reported) | ~95% | ~0.1 ms | 0% (process only) | Low (returns 200 on failure) | | Layer 2 Real Roundtrip (Recommended) | <1 min (deploy-time) | ~5% | 2–5 ms | ~80% (DB/Auth/Pool) | High (returns 503 on failure) | | Layer 3 Deep System Check | <1 min | ~2% | 50–100 ms | ~95% (Workers/Cron/Queue) | High |

Key Findings:

• A head: true count query exercises connection pool acquisition, auth validation, and table existence in microseconds without transferring payload data.
• Returning 503 Service Unavailable instead of 200 { ok: false } ensures upstream monitors (K8s probes, AWS/GCP health checks, external uptime tools) correctly remove unhealthy instances from rotation.
• External monitoring from multiple regions is mandatory to catch infrastructure-layer failures (DNS, TLS, CDN, BGP) that internal probes cannot see.

Core Solution

The following Next.js 13+ Route Handler implements a production-grade Layer 2 health check. It uses Supabase as an example, but the pattern applies to any database or dependency.

// src/app/api/health/route.ts
import { NextResponse } from "next/server";
import { createSupabaseServiceRole } from "@/lib/supabase/server";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

export async function GET() {
  try {
    const supabase = createSupabaseServiceRole();

    // Cheapest possible call that exercises the connection pool + auth.
    // head: true returns no rows — microseconds, no payload.
    const { error } = await supabase
      .from("profiles")
      .select("id", { count: "exact", head: true })
      .limit(1);

    if (error) throw error;

    return NextResponse.json(
      { ok: true, ts: Date.now() },
      { headers: { "Cache-Control": "no-store" } }
    );
  } catch (e) {
    return NextResponse.json(
      { ok: false, error: (e as Error).message },
      { status: 503, headers: { "Cache-Control": "no-store" } }
    );
  }
}

Architecture Decisions:

1. runtime = "nodejs": Health checks must execute in the same runtime as production traffic. Edge runtimes bypass Node.js-specific connection pooling and module resolution, masking runtime-specific failures.
2. dynamic = "force-dynamic": Prevents Next.js or CDN caching from serving stale 200 OK responses after dependencies fail.
3. Cache-Control: no-store: Enforces cache bypass at the HTTP layer. CDNs respect this header even if framework-level caching misbehaves.
4. Real DB roundtrip (head: true): Replaces fake SELECT 1 queries. Exercises pool acquisition, auth tokens, and actual table schemas. Transfers zero rows, costing microseconds.
5. 503 on failure: Upstream orchestrators trigger on HTTP status codes, not JSON payloads. 503 correctly signals "running but unable to serve traffic," enabling automatic pod eviction or rollback.

For Kubernetes conventions, map /healthz to the handler via next.config.js:

module.exports = {
  rewrites: async () => [
    { source: "/healthz", destination: "/api/health" },
  ],
};

Pitfall Guide

1. Returning 200 with { ok: false } on failure: Orchestrators and uptime monitors parse HTTP status codes, not response bodies. Returning 200 keeps broken instances in the load balancer rotation, prolonging customer-facing outages.
2. Mismatched Runtime (edge vs nodejs): Testing against the Edge runtime while production runs on Node.js hides connection pool limits, native module dependencies, and timeout behaviors unique to the Node.js execution environment.
3. Missing Cache Invalidation (dynamic + Cache-Control): Without explicit cache bypass, CDNs or Next.js ISR can serve a cached 200 for minutes after a database outage, creating a false sense of system health.
4. Using Fake Queries (SELECT 1): Raw SQL pings bypass application-layer auth, connection pool limits, and schema validation. They fail to catch expired service tokens, pool exhaustion, or migration drift.
5. Relying Solely on Internal Probes: Platform liveness checks only verify pod reachability. They cannot detect DNS expiration, TLS certificate failures, CDN edge degradation, or third-party API outages. External multi-region monitoring is mandatory.
6. Ignoring Environment Drift: CI/staging environments often use different configs than production. A health check that passes in CI but uses production env vars will catch drift at deploy-time, preventing silent 500 cascades.

Deliverables

• Blueprint: Next.js Health Check Architecture Blueprint — Covers runtime alignment, cache bypass strategies, dependency roundtrip design, HTTP status mapping, and external monitoring topology.
• Checklist: Pre-Deploy Health Validation Checklist — Verifies runtime/dynamic config, Cache-Control headers, 503 failure routing, real dependency queries, and external monitor registration.
• Configuration Templates: Production-ready route.ts handler, next.config.js rewrite mapping, and external uptime monitor payload schema for multi-region validation.