Custom error pages
Custom error pages are available on Enterprise plans
Custom error pages let you replace Vercel's platform error pages with your own branded experience. These include errors like function invocation timeouts or when your functions are throttled.
Custom error pages help you:
- Maintain brand consistency: Keep your visual identity intact even during platform outages
- Improve user experience: Provide helpful messaging, support links, or status page references
- Reduce user confusion: Guide users on what to do next instead of showing a technical error
When you deploy your project, Vercel automatically scans your build output for error pages and configures routes to cover all platform errors. For most cases, you only need to create a single 500 error page. Vercel automatically uses it as the fallback for all platform errors, so you don't need to design a separate page for each error type.
If a custom error page exists for a specific status code, Vercel uses it; otherwise, it falls back to your 500 error page if one exists.
You can include request IDs and error codes in your error pages using metadata tokens. When Vercel serves a custom error page, it replaces these tokens with actual values.
| Token | Description |
|---|---|
::vercel:REQUEST_ID:: | Matches the x-vercel-id header value |
::vercel:ERROR_CODE:: | The error code (e.g., FUNCTION_INVOCATION_TIMEOUT) |
Vercel strongly recommends embedding these tokens to help users reference a specific request when contacting support.
Custom error pages must be static files in your build output. Common approaches include:
- Static HTML files (e.g.,
500.html,504.html) - Framework error pages (Next.js App Router:
app/500/page.tsx, Pages Router:pages/500.tsx) - Files in your public directory
For example, a simple way to create a custom error page is to add a static 500.html file to your project's public directory:
<!doctype html>
<html>
<head>
<title>Something went wrong</title>
</head>
<body>
<h1>Something went wrong</h1>
<p>We're working on it. Please try again later.</p>
<p>Request ID: ::vercel:REQUEST_ID::</p>
<p>Error: ::vercel:ERROR_CODE::</p>
</body>
</html>Deploy your project, and Vercel will serve this page for all platform errors.
For example, if you add only two custom error pages (500.html and 504.html), the routing behavior will be as follows:
| Error | Destination |
|---|---|
| 500 | /500.html |
| 501...503 | /500.html (fallback) |
| 504 | /504.html |
| 505...511 | /500.html (fallback) |
- Custom error pages must be static. Since these pages handle platform errors, they can't rely on server-side rendering or dynamic content that might also fail.
Was this helpful?