Interactive Troubleshooter

Published: Sep 6, 2026

Next.js API Route 504 Timeout: Serverless Fix

Time: 15 mins Level: Beginner

By StepDiag Engineering Team

Reviewed by Ibraheem Taofeeq Opeyemi

An interactive guide to resolve Next.js API route 504 timeouts across Vercel and serverless environments. Troubleshoot maxDuration limits, cold starts, unhandled async promises, and database connection pooling.

Full Diagnostic Tree & Step-by-Step Overview

What specific symptom, platform environment, or error log accompanies your Next.js API Route 504 Gateway Timeout?

Vercel deployment logs show FUNCTION_INVOCATION_TIMEOUT or 504 error after 10s, 15s, or 60s of execution.
API route hangs or times out while querying databases (Prisma, PostgreSQL) or awaiting external fetch calls.
Timeout occurs intermittently during initial request execution, cold starts, or unhandled async promises.
Self-hosted Next.js deployment (Docker, NGINX, PM2) returns 504 Gateway Timeout from the reverse proxy.

Which serverless execution behavior or route implementation matches your deployment state?

Route execution time exceeds Vercel default function duration limits (10s on Hobby, 15s on Pro/Enterprise).
App Router handler hangs because a large response or stream payload is buffered before sending headers.
Heavy synchronous CPU calculations (PDF generation, image processing) block the Node.js event loop.

Configure maxDuration and Route Segment Configs for Extended Execution

Solution:

Root Cause: Exceeded Serverless Function Default maxDuration Limits

Vercel and cloud platforms enforce hard execution limits on serverless functions to prevent runaway billing and resource consumption. In Next.js App Router, routes default to a 10-second limit on Hobby plans and 15 seconds on Pro plans unless explicitly overridden. If an API route handler takes longer than this duration to return a response, the edge proxy terminates the HTTP connection with 504 Gateway Timeout and logs FUNCTION_INVOCATION_TIMEOUT.

Step-by-Step Fix:

1Update Route Handler Config in App Router:

Open your API route file (e.g., app/api/data/route.ts).

Export the maxDuration segment configuration option to extend execution limits (up to 60s on Pro, or 300s/900s on Enterprise/Fluid Compute):

typescript
     export const maxDuration = 60; // Set timeout limit in seconds
     export const dynamic = 'force-dynamic';

     export async function POST(request: Request) {
       // Long-running API logic
       return Response.json({ success: true });
     }

2Update Global Configuration in vercel.json (Optional Alternative):

Define function duration globally in your root vercel.json:

json
     {
       "functions": {
         "app/api/**/*": {
           "maxDuration": 60
         }
       }
     }

3Review Platform Limits:

Check the Vercel Serverless Function Duration Docs to confirm plan-specific maximum execution constraints.

Refactor Route Handler to Stream Responses via ReadableStream

Solution:

Root Cause: Buffered HTTP Header Delays and Gateway Connection Inactivity

When a Next.js API route attempts to aggregate large datasets or wait for slow AI model outputs before returning a single NextResponse.json(), the serverless gateway maintains an idle socket. If no HTTP response headers or chunks are flushed to the client within the gateway's idle socket window, edge proxies close the connection with a 504 error even if the backend process is still actively working.

Step-by-Step Fix:

1Implement Web Streams API in App Router:

Use ReadableStream to flush HTTP status headers immediately and stream data chunks as they become available:

typescript
     export async function GET() {
       const stream = new ReadableStream({
         async start(controller) {
           const encoder = new TextEncoder();
           controller.enqueue(encoder.encode('Processing started...\n'));
           
           // Perform chunked work
           const data = await fetchLongRunningData();
           controller.enqueue(encoder.encode(JSON.stringify(data)));
           controller.close();
         },
       });

       return new Response(stream, {
         headers: { 'Content-Type': 'text/plain; charset=utf-8' },
       });
     }

2Utilize AI SDK Streaming Helpers (If Applicable):

For LLM or AI routes, use StreamingTextResponse or createDataStreamResponse from the ai SDK to stream responses without hitting socket idle timeouts.

Offload CPU-Intensive Tasks to Async Background Worker Queues

Solution:

Root Cause: Node.js Event Loop Blocking during Synchronous CPU Computation

Serverless function environments execute on single-threaded Node.js runtimes. Synchronous, CPU-heavy tasks—such as generating PDFs (puppeteer), processing images (sharp), or parsing multi-megabyte JSON files—block the Node.js event loop entirely. This prevents the serverless process from handling I/O events or sending keep-alive signals, causing gateway timeout monitors to drop the socket.

Step-by-Step Fix:

1Convert Synchronous Processing to Async Queue Architecture:

Instead of processing inline, send a payload to an external queue service (e.g., QStash, Inngest, BullMQ, AWS SQS) and return an immediate 202 Accepted response:

typescript
     import { Client } from '@upstash/qstash';

     const qstash = new Client({ token: process.env.QSTASH_TOKEN! });

     export async function POST(request: Request) {
       const payload = await request.json();
       
       // Enqueue background job
       const { messageId } = await qstash.publishJSON({
         url: '[https://yourdomain.com/api/workers/process-pdf](https://yourdomain.com/api/workers/process-pdf)',
         body: payload,
       });

       return Response.json({ status: 'queued', jobId: messageId }, { status: 202 });
     }

2Poll or Use Webhooks for Completion:

Have the client poll a status endpoint (/api/jobs/[id]) or receive a WebSocket/webhook callback once the worker completes.

Which database connection pattern or external I/O dependency is causing the execution delay?

Prisma or raw PostgreSQL connection exhaustion and cold connection handshakes in serverless lambdas.
External third-party API fetch calls hanging indefinitely without timeout control.
Missing database table indexes resulting in slow full-table scans under production data volume.

Implement Serverless Database Connection Pooling and Proxy Drivers

Solution:

Root Cause: Direct Database Connection Starvation in Ephemeral Runtimes

In traditional Node.js servers, a single persistent process shares a database connection pool. In serverless Next.js, every concurrent request spins up an isolated lambda instance. Opening direct TCP connections to databases like PostgreSQL or MySQL on every request rapidly exhausts the database's max_connections pool. Subsequent requests queue until the API route hits the 504 timeout waiting for a free DB socket.

Step-by-Step Fix:

1Enable Connection Pooling or HTTP Proxy Drivers:

For Prisma: Use Prisma Accelerate or configure PgBouncer / Supabase Connection Pooler in DATABASE_URL using transaction mode (pgbouncer=true&connection_limit=1).

For Neon/PostgreSQL: Use the HTTP-based serverless driver (@neondatabase/serverless) to bypass TCP handshakes entirely.

2Instaniate Global Client Singletons in Next.js:

Prevent creating multiple ORM client instances during development hot-reloading in lib/db.ts:

typescript
     import { PrismaClient } from '@prisma/client';

     const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };

     export const prisma = globalForPrisma.prisma || new PrismaClient();

     if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

Implement AbortSignal Timeout Handling on Outbound Fetch Calls

Solution:

Root Cause: Unbounded Outbound HTTP Requests Hanging the Function

By default, the global fetch() implementation in Node.js and Next.js does not enforce a request timeout. If an API route depends on a remote third-party REST or SOAP service that experiences latency or silent packet loss, the Next.js API handler remains suspended indefinitely waiting for socket resolution until the platform serverless gateway forcibly terminates the route with a 504 error.

Step-by-Step Fix:

1Apply AbortSignal.timeout to External Fetch Calls:

Pass an AbortSignal with a strict cutoff time shorter than your serverless maxDuration:

typescript
     export async function GET() {
       try {
         const response = await fetch('[https://api.external-service.com/data](https://api.external-service.com/data)', {
           // Abort if external request takes longer than 5 seconds
           signal: AbortSignal.timeout(5000),
         });
         const data = await response.json();
         return Response.json(data);
       } catch (error) {
         if (error.name === 'AbortError' || error.name === 'TimeoutError') {
           return Response.json({ error: 'External service timeout' }, { status: 504 });
         }
         return Response.json({ error: 'Internal Server Error' }, { status: 500 });
       }
     }

Optimize Database Query Performance, Indexes, and Field Projections

Solution:

Root Cause: Unindexed Database Queries and Over-fetching Large Schemas

An API route that executes quickly in local development with minimal seed data can fail in production as database tables scale. Executing queries missing composite indexes on WHERE, JOIN, or ORDER BY clauses forces the database engine into full sequential table scans, driving query duration past the function execution limit.

Step-by-Step Fix:

1Analyze Slow Queries with EXPLAIN ANALYZE:

Run explain plans directly on slow queries via your database console:

sql
     EXPLAIN ANALYZE SELECT id, status FROM orders WHERE user_id = 'usr_123' ORDER BY created_at DESC;

2Add Missing Composite Indexes:

Add targeted indexes to your schema (e.g., in schema.prisma):

prisma
     model Order {
       id        String   @id @default(cuid())
       userId    String
       createdAt DateTime @default(now())

       @@index([userId, createdAt(sort: Desc)])
     }

3Restrict Query Select Fields:

Avoid returning entire table schemas. Use ORM field projection to fetch only required properties:

typescript
     const user = await prisma.user.findUnique({
       where: { id },
       select: { id: true, email: true }, // Avoid fetching large JSON blobs or heavy relations
     });

Which runtime initialization, promise lifecycle, or Edge targeting issue is occurring?

Severe cold start delays caused by heavy top-level imports and large serverless bundle sizes.
Unhandled background promises or missing await calls cause runtime freezes upon returning NextResponse.
Next.js Edge Runtime incompatibility or missing dynamic route segment export configuration.

Reduce Bundle Size and Dynamic Imports to Mitigate Serverless Cold Starts

Solution:

Root Cause: High Cold Start Latency from Heavy Module Scoping

When a serverless function scales up from zero, cloud providers must download the function artifact, initialize the Node.js runtime, and execute top-level JavaScript imports before processing the request. Importing massive SDKs (such as the full AWS SDK v2 or heavy image processing libraries) at the top of the file inflates cold start times, pushing initial request execution beyond gateway timeout limits.

Step-by-Step Fix:

1Leverage Dynamic Imports for Heavy Libraries:

Move heavy dependencies inside the handler function so they only load when the route is invoked:

typescript
     export async function POST(request: Request) {
       // Dynamic import defers loading until execution
       const { Sharp } = await import('sharp');
       // Process payload
     }

2Use Modular Library Imports:

Replace monolithic package imports with modular packages (e.g., use @aws-sdk/client-s3 instead of aws-sdk).

3Enable Standalone Output Mode in next.config.mjs:

Optimize deployment bundle sizes by trimming unused node_modules:

javascript
     /** @type {import('next').NextType} */
     const nextConfig = {
       output: 'standalone',
     };
     export default nextConfig;

Review the Next.js Output Standalone Documentation for deployment optimization details.

Ensure Proper Async/Await Execution and Use waitUntil for Background Tasks

Solution:

Root Cause: Early Function Return and Unhandled Async Lifecycle Freezes

In serverless runtimes, as soon as a Next.js route handler returns a Response object, the underlying execution context is immediately paused or frozen by the infrastructure provider. If your code triggers async operations (e.g., analytics logging or DB writes) without using await, the background work hangs mid-execution. On subsequent invocations, the frozen event loop resumes in an corrupted state, leading to socket hangs and 504 timeouts.

Step-by-Step Fix:

1Explicitly Await All Async Promises:

Ensure all asynchronous functions are fully resolved before returning the response object.

2Use waitUntil from @vercel/functions for Non-Blocking Work:

If you need to perform non-blocking tasks after returning a response, use waitUntil to keep the lambda context active:

typescript
     import { waitUntil } from '@vercel/functions';

     export async function POST(request: Request) {
       const data = await request.json();
       
       // Schedule non-blocking background task without delaying response
       waitUntil(
         saveAnalytics(data).catch((err) => console.error('Analytics failed', err))
       );

       return Response.json({ success: true });
     }

Configure Route Segment Options and Edge/Node.js Runtime Targeting

Solution:

Root Cause: Runtime Incompatibility or Incorrect Static Caching Evaluation

By default, Next.js routes dynamically select runtimes based on code usage or global settings. Deploying a route intended for Node.js (utilizing native C++ bindings or Node APIs like fs or net) on the Edge Runtime will cause execution failures or hung invocations. Conversely, static route optimization on dynamic API endpoints can cause proxy caching confusion.

Step-by-Step Fix:

1Explicitly Define Runtime Targeting in Route Handler:

Force the appropriate runtime explicitly in your route.ts file:

typescript
     // Force Node.js runtime if using standard Node.js APIs or heavy DB drivers
     export const runtime = 'nodejs';
     
     // Force dynamic rendering to prevent static build caching stalls
     export const dynamic = 'force-dynamic';

     export async function GET(request: Request) {
       return Response.json({ timestamp: Date.now() });
     }

2Clear Build Cache and Redeploy:

Rebuild the application locally using npx next build to verify there are no runtime compilation errors.

Which self-hosted infrastructure or reverse proxy setup is dropping connection sockets?

NGINX reverse proxy terminates connection before Next.js Node server finishes processing.
Docker container memory saturation or Node.js heap exhaustion causes process garbage collection freezes.
PM2 process manager cluster mode workers become unresponsive due to socket leaks.

Adjust NGINX Reverse Proxy Read and Connect Timeout Directives

Solution:

Root Cause: NGINX Upstream Proxy Timeout Misconfiguration

When self-hosting Next.js behind an NGINX reverse proxy, NGINX enforces its own timeout counters independent of Node.js. By default, NGINX limits proxy_read_timeout to 60 seconds. If a Next.js API route takes longer than 60 seconds (or custom NGINX timeout values are set too low), NGINX drops the upstream connection and returns 504 Gateway Time-out to the browser.

Step-by-Step Fix:

1Update NGINX Location Block Configuration:

Edit your NGINX site configuration file (e.g., /etc/nginx/sites-available/default):

nginx
     location /api/ {
         proxy_pass [http://127.0.0.1:3000](http://127.0.0.1:3000);
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection 'upgrade';
         proxy_set_header Host $host;
         proxy_cache_bypass$http_upgrade;

         # Increase proxy timeouts for long-running API routes
         proxy_connect_timeout 120s;
         proxy_send_timeout    120s;
         proxy_read_timeout    120s;
     }

2Test and Reload NGINX:

Validate syntax and apply settings:

bash
     sudo nginx -t
     sudo systemctl reload nginx

Configure Node.js Heap Size Limits and Docker Memory Allocation

Solution:

Root Cause: Node.js Memory Exhaustion and Garbage Collection Stalls

In self-hosted Docker environments, if the Node.js process approaches its allocated V8 heap limit (defaulting to ~2GB or ~4GB depending on architecture), the runtime initiates aggressive, synchronous Garbage Collection (GC) sweeps. These 'Stop-The-World' GC cycles freeze the single-threaded event loop for several seconds, causing incoming proxy requests to time out at the gateway level.

Step-by-Step Fix:

1Increase Node.js Max Old Space Size:

Pass the --max-old-space-size flag via environment variables in your Dockerfile or system systemd service:

dockerfile
     ENV NODE_OPTIONS="--max-old-space-size=4096"

2Adjust Docker Container Resource Constraints:

Ensure your docker-compose.yml or container runner allocates sufficient physical host memory to prevent OOM thrashing:

yaml
     services:
       nextjs-app:
         image: nextjs-app:latest
         deploy:
           resources:
             limits:
               memory: 6G
             reservations:
               memory: 2G

Tune PM2 Cluster Manager Settings and Configure Keep-Alive Timeouts

Solution:

Root Cause: PM2 Worker Pool Exhaustion and HTTP Keep-Alive Mismatches

When running Next.js in cluster mode via PM2, load is distributed across multiple worker instances. If an unhandled memory leak or dangling socket lock occurs on a worker instance, PM2 continues routing incoming connections to the hung worker process until HTTP sockets time out. Additionally, if the reverse proxy's keep-alive timeout is longer than Next.js's internal keep-alive timeout, race-condition socket drops occur.

Step-by-Step Fix:

1Configure Automatic Memory Restarts in PM2 ecosystem.config.js:

Define automatic worker recycling rules:

javascript
     module.exports = {
       apps: [{
         name: 'nextjs-app',
         script: 'node_modules/next/dist/bin/next',
         args: 'start',
         instances: 'max',
         exec_mode: 'cluster',
         max_memory_restart: '1G',
         env: {
           NODE_ENV: 'production',
         }
       }]
     };

2Reload PM2 Process Cluster:

Gracefully restart cluster workers without downtime:

bash
     pm2 reload ecosystem.config.js --update-env

Related Diagnostic Guides

Windows Update Error 0x80070002 Missing Files Diagnostic Guide

System Restore Failed 0x80070005 Antivirus Conflict Tree

Windows Photo Viewer Not Showing Thumbnails: Codec Diagnostic

Safe Mode Password Not Working With Microsoft Account Fix

Clipboard History Not Working Windows 11: Sync Service Tree

Subscribe to StepDiag

Embed Guide on Your Website