A Next.js route handler is cut off after a fixed time
Route handler stops after a fixed number of seconds on production but not locallyShort answer
Next.js does not enforce a timeout itself. The limit comes from where it runs. On Vercel, export maxDuration from the route file, within your plan's limit. When you self-host, maxDuration changes nothing: the cut-off is usually the reverse proxy, such as nginx proxy_read_timeout at 60 seconds.
Fix it fast
1Find out which cause you have
Time the failing request. If it dies at a round number such as 10, 60 or 300 seconds, that number is a platform or proxy limit, and it tells you which cause applies.
time curl -s -o /dev/null -w "%{http_code}\n" https://example.com/api/report2Match what you see, then jump to its fix
- 1
The request ends at your platform's default durationmaxDuration is not exported on the route (Vercel)Fix - 2
maxDuration is set above your plan limit, and the function still stops at the plan maximumThe value is above what your Vercel plan allowsFix - 3
The request dies near 60 seconds behind nginx, and the handler keeps no limit of its ownSelf-hosted: nginx closes the connection firstFix
- 1
What does the error look like?
Route handler stops after a fixed number of seconds on production but not locallyLong request returns a gateway timeout from nginx
Cause 1 of 3
maxDuration is not exported on the route (Vercel)
1Check
Next.js documents maxDuration as the maximum execution time in seconds for a route segment, and says deployment platforms can use it from the build output.
grep -rn "maxDuration" app2Fix
Export it from the route file. For Server Actions, export it at page level to change the timeout of all actions on that page.
// app/api/report/route.ts
export const maxDuration = 60
export async function GET() {
// long work
return Response.json({ ok: true })
}3Verify
Redeploy and repeat the slow request.
time curl -s -o /dev/null -w "%{http_code}\n" https://example.com/api/reportConfirmed by nextjs.org
Cause 2 of 3
The value is above what your Vercel plan allows
1Check
Vercel's table for functions with Fluid compute lists a default of 300 seconds on all plans, a maximum of 300 seconds on Hobby and 800 seconds on Pro and Enterprise.
npx vercel inspect <deployment-url> --json2Fix
Lower maxDuration to the plan maximum. You can also set a project-wide default in vercel.json.
{
"functions": {
"app/api/**/*": { "maxDuration": 300 }
}
}3Verify
The inspect output lists each function's timeout; it should show your value.
npx vercel inspect <deployment-url> --jsonConfirmed by vercel.com
Cause 3 of 3
Self-hosted: nginx closes the connection first
1Check
nginx proxy_read_timeout defaults to 60 seconds. It counts the silence between two reads from the app, so a handler that sends nothing for a minute is closed.
grep -rn "proxy_read_timeout" /etc/nginx/2Fix
Raise it for that location, or stream progress so the connection is never silent.
location /api/report {
proxy_pass http://127.0.0.1:3000;
proxy_read_timeout 300s;
}3Verify
Test the config, reload nginx, and repeat the slow request.
sudo nginx -t && sudo systemctl reload nginxConfirmed by nginx.org
How do I stop it coming back?
- Set maxDuration on every route that calls a slow third-party API.
- Move jobs that take minutes to a queue and return a job id.
- Keep proxy and platform timeouts longer than the slowest route you expect.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The browser blocks your API response: no Access-Control-Allow-Origin header
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://api.example.com/orders. (Reason: CORS header 'Access-Control-Allow-Origin' missing).
The browser received the response but refused to hand it to your script, because it did not carry an Access-Control-Allow-Origin header naming the page's origin.
4 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fix