Next.js maxDuration
Serverless execution environments generally enforce a hard ceiling on how long any single invocation is allowed to run — exceed it, and the platform kills the function regardless of whether it was about to finish. maxDuration is how you tell Next.js (and, through it, your deployment platform) what that ceiling should be for a specific route segment, rather than relying entirely on whatever the platform's default happens to be.
Basic Usage
export const maxDuration = 5;
The value is a number, in seconds. This is one of the simpler route segment config options in terms of API surface — a single number, no enum of named strings to choose between.
What This Actually Does — and Doesn't Do
Here's the detail worth being precise about: maxDuration is a signal Next.js passes through in its build output; it doesn't independently enforce anything at the framework level. Deployment platforms read this value from the build output and apply it as an actual execution limit on their side. If your platform ignores the value, or if you're self-hosting without a platform that consumes this signal, setting maxDuration alone accomplishes nothing on its own — it's a hint that specific hosting infrastructure needs to be listening for and honoring, not a guarantee Next.js itself enforces at runtime.
Practically, this means the exact behavior when a segment exceeds its configured duration — whether it's terminated at precisely that limit, whether there's a platform-specific default ceiling if you don't set this at all, what error the client actually sees — depends entirely on your specific deployment platform's own documentation, not on anything Next.js controls directly.
Server Actions Have a Special Rule Here
For Server Actions specifically, there's a scoping detail worth knowing: setting maxDuration at the page level changes the default timeout for every Server Action used on that page — not just for the page's own rendering. If a page has several distinct Server Actions attached to different forms or interactions, they all inherit that one page-level maxDuration value as their shared timeout ceiling, rather than each needing its own separate configuration. If different Server Actions on the same page genuinely need different timeout budgets, that's not something this single page-level export can express on its own — you'd need to structure those actions across different routes, or handle the finer-grained timeout logic inside the action itself rather than relying purely on this config option.
Version History
| Version | Changes |
|---|---|
v13.4.10 | maxDuration introduced |
Key Takeaways
| Aspect | Detail |
|---|---|
| Value type | A number, in seconds |
| Enforcement | Passed through to your deployment platform — Next.js doesn't enforce it independently |
| Server Actions | A page-level maxDuration sets the default timeout for every Server Action on that page |
| Self-hosting | Only meaningful if your hosting setup actually reads and applies this build-output signal |
maxDuration is a small but genuinely important knob for anything doing real work on the server — a slow third-party API call, a heavier data transformation — where the platform's default timeout might be either too generous (letting a hung request tie up resources longer than it should) or too strict (killing legitimate slow-but-successful work prematurely). Set it deliberately based on what your platform actually supports and enforces, rather than assuming a number here changes behavior on its own.
