Next.js 15 Async Request Context Boundary & Unhandled Promise Isolation

--- description: Next.js 15 Async Request Context Boundary & Unhandled Promise Isolation - Enforces deterministic resolution and strict boundary isolation for Next.js 15 asynchronous request APIs (cookies, headers, params, and searchParams). Prevents dynamic AsyncLocalStorage context detachment, worker thread deadlocks, and unhandled promise rejections caused by floating promises crossing request lifecycle boundaries. globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, middleware.ts, src/middleware.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-async-request-context-unhandled-promise-isolation" --- # Next.js 15 Async Request Context Boundary & Unhandled Promise Isolation > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Leaking Unresolved Dynamic Request Promises Across Async Boundaries or Background Tasks ## System Constraints You are a Principal Engineer enforcing Next.js 15 Async Request Context Unhandled Promise Isolation. In Next.js 15, dynamic request APIs (`cookies()`, `headers()`, `params`, and `searchParams`) return Promises governed by internal AsyncLocalStorage lifecycles. You must mandate that dynamic context promises are awaited at the immediate execution entry point, extracted into immutable primitive snapshots prior to asynchronous handoffs, and strictly quarantined from unawaited detached promises, caching contexts (`unstable_cache`), and global singletons. ## Strict Guidelines - Engineers MUST ALWAYS immediately await `cookies()`, `headers()`, `params`, and `searchParams` at the immediate entry point of Route Handlers, Server Actions, or Server Components. - Engineers MUST NOT pass raw unawaited request-context Promises into deferred execution boundaries, background tasks, or `unstable_cache` scopes. - Code MUST extract required scalar values (e.g., token strings, specific header values) into plain variables before passing telemetry or audit calls to `after()` or external logging sinks. - Services MUST NEVER bind unresolved or resolved request-context instances to module-level singletons or cross-request static variables. - Components NEVER forward unawaited `params` or `searchParams` promises to client components or deeply nested asynchronous helper functions without explicit resolution or `use()` boundaries. ## Bad vs Good Implementations ### Route Handler Dynamic Context Resolution & Background Task Isolation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Passing the unresolved `cookies()` promise into an unawaited background closure allows execution to continue after the response lifecycle has terminated. This detaches Next.js AsyncLocalStorage, causing runtime context abandonment and unhandled promise rejections on concurrent worker threads. ```typescript import { cookies, headers } from 'next/headers'; import { NextRequest, NextResponse } from 'next/server'; export async function POST(req: NextRequest) { // ANTI-PATTERN: Leaking unawaited context promises into floating background work const cookieStorePromise = cookies(); const headersListPromise = headers(); // Floating unhandled promise escaping request boundary void (async () => { const store = await cookieStorePromise; const sessionToken = store.get('session_id')?.value; await fetch('https://telemetry.internal/log', { method: 'POST', body: JSON.stringify({ sessionToken }), }); })(); return NextResponse.json({ status: 'ok' }); } ``` #### Production Standard (Correct) > **Standard**: Request contexts are immediately awaited and distilled into primitive scalar types within the active request scope. Background processing is delegated to Next.js 15's native `after()` API with full error encapsulation, preventing AsyncLocalStorage leakage and deadlocks. ```typescript import { cookies, headers } from 'next/headers'; import { after } from 'next/server'; import { NextRequest, NextResponse } from 'next/server'; export async function POST(req: NextRequest) { // Invariant Fix: Await synchronously within request scope and extract scalar values const cookieStore = await cookies(); const headersList = await headers(); const sessionToken = cookieStore.get('session_id')?.value ?? null; const userAgent = headersList.get('user-agent') ?? 'unknown'; // Isolated background task using Next.js 15 `after` lifecycle with pre-resolved scalars after(async () => { if (!sessionToken) return; try { await fetch('https://telemetry.internal/log', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionToken, userAgent }), }); } catch (error) { console.error('Background telemetry failed:', error); } }); return NextResponse.json({ status: 'ok' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 Async Request Context Boundary & Unhandled Promise Isolation

Next.js 15 Async Request Context Boundary & Unhandled Promise Isolation defines an industrial-grade behavioral standard for frontend engineering. Enforces deterministic resolution and strict boundary isolation for Next.js 15 asynchronous request APIs (cookies, headers, params, and searchParams). Prevents dynamic AsyncLocalStorage context detachment, worker thread deadlocks, and unhandled promise rejections caused by floating promises crossing request lifecycle boundaries. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Leaking Unresolved Dynamic Request Promises Across Async Boundaries or Background Tasks Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Leaking Unresolved Dynamic Request Promises Across Async Boundaries or Background Tasks	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS immediately await `cookies()`, `headers()`, `params`, and `searchParams` at the immediate entry point of Route Handlers, Server Actions, or Server Components.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.