Next.js 15 after() Background Task Boundary and Execution Timeout Guardrail

--- description: Next.js 15 after() Background Task Boundary and Execution Timeout Guardrail - Governs the usage of the Next.js 15 after() API within Server Components, Server Actions, and Route Handlers. Mandates strict execution timeouts, comprehensive error isolation, and cancellation semantics to prevent unhandled promise rejections, stalled serverless microVM teardowns, and zombie telemetry tasks. globs: app/**/*.{ts,tsx}, src/app/**/*.{ts,tsx}, lib/**/*.{ts,tsx}, src/lib/**/*.{ts,tsx} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nextjs-15-after-background-task-timeout-guardrail" --- # Next.js 15 after() Background Task Boundary and Execution Timeout Guardrail > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Unbounded floating promises and unisolated after() callbacks starving serverless concurrency and throwing unhandled rejections ## System Constraints You are a Principal Software Architect enforcing production reliability standards for Next.js 15 applications running in serverless and containerized environments. You must enforce that any secondary side effects (telemetry, cache warmups, audit logging) executed after the HTTP response stream has been closed strictly utilize Next.js 15's after() API bounded by explicit timeouts and top-level error boundaries. ## Strict Guidelines - Engineers MUST ALWAYS wrap non-critical background jobs (audit logging, metric aggregation, webhooks) in Next.js 15's `after()` from `next/server` rather than initiating unhandled floating promises (`void doTask()`). - Engineers MUST NEVER `await` the invocation of `after()` itself, as doing so blocks the response stream and negates the non-blocking execution lifecycle. - Code inside `after()` MUST implement an explicit execution deadline via `AbortController` or `Promise.race` (typically capped at 5000ms–8000ms) to ensure background tasks terminate before serverless function execution freezes. - Callbacks passed to `after()` MUST encapsulate all asynchronous code in a top-level `try/catch` block, explicitly catching and logging errors to prevent unhandled rejection crashes in the runtime host process. - Engineers MUST NOT read mutable request headers, searchParams, or dynamic cookies directly inside `after()` without pre-capturing needed scalar values in the parent handler scope, as the request context may be closed. - Services invoked within `after()` MUST be idempotent to prevent corrupted state if retried by upstream infrastructure upon serverless invocation reclaim. ## Bad vs Good Implementations ### Floating Promise vs. Timeout-Guarded after() in Next.js 15 Route Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing raw floating promises inside a serverless runtime causes the runtime environment to freeze execution as soon as the response is returned. The promise may never resolve, or it may wake up during an unrelated request. If it throws, it leads to unhandled rejection errors that crash the container. ```typescript import { NextResponse } from 'next/server'; import { recordUserAudit } from '@/lib/audit'; export async function POST(request: Request) { const payload = await request.json(); // BAD: Floating promise executed outside request lifecycle. // In serverless (AWS Lambda/Vercel), this promise can freeze mid-flight, // causing zombie execution or silent telemetry drops on container freeze. recordUserAudit(payload); return NextResponse.json({ status: 'queued' }); } ``` #### Production Standard (Correct) > **Standard**: Utilizes Next.js 15's `after()` to register work guaranteed to execute during the cleanup phase. Captures context scalars early, enforces a strict 5000ms timeout boundary via AbortController to prevent hanging the serverless microVM, and guarantees catch-all error handling so unhandled rejections never escape to the runtime. ```typescript import { NextResponse } from 'next/server'; import { after } from 'next/server'; import { recordUserAudit } from '@/lib/audit'; import { logger } from '@/lib/logger'; const BACKGROUND_TASK_TIMEOUT_MS = 5000; export async function POST(request: Request) { const payload = await request.json(); // Pre-capture immutable execution context before response finishes const eventData = { ...payload, timestamp: Date.now() }; after(async () => { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), BACKGROUND_TASK_TIMEOUT_MS); try { await recordUserAudit(eventData, { signal: controller.signal }); } catch (err: unknown) { if (err instanceof Error && err.name === 'AbortError') { logger.warn('Background audit task aborted due to timeout', { eventData }); } else { logger.error('Background audit task failed', { error: err, eventData }); } } finally { clearTimeout(timeoutId); } }); return NextResponse.json({ status: 'queued' }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Next.js 15 after() Background Task Boundary and Execution Timeout Guardrail

Next.js 15 after() Background Task Boundary and Execution Timeout Guardrail defines an industrial-grade behavioral standard for frontend engineering. Governs the usage of the Next.js 15 after() API within Server Components, Server Actions, and Route Handlers. Mandates strict execution timeouts, comprehensive error isolation, and cancellation semantics to prevent unhandled promise rejections, stalled serverless microVM teardowns, and zombie telemetry tasks. 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: Unbounded floating promises and unisolated after() callbacks starving serverless concurrency and throwing unhandled rejections 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	Unbounded floating promises and unisolated after() callbacks starving serverless concurrency and throwing unhandled rejections	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 wrap non-critical background jobs (audit logging, metric aggregation, webhooks) in Next.js 15's `after()` from `next/server` rather than initiating unhandled floating promises (`void doTask()`).

Engineers MUST ALWAYS wrap non-critical background jobs (audit logging, metric aggregation, webhooks) in Next.js 15's `after()` from `next/server` rather than initiating unhandled floating promises (`void doTask()`).

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.