Unverified Commit c74cb2ae authored by Jimmy Lai's avatar Jimmy Lai Committed by GitHub

Redesign default error pages with cleaner, more user-friendly UI (#87988)

- redesigns the default global + default error boundaries. removing the
WSOD forever :/
- adds dark mode support
- unifies a bit of the styling
- add the digest for the server error
- adds a return button on the client errors

<img width="3328" height="1914" alt="CleanShot 2026-01-02 at 09 46
36@2x"
src="https://github.com/user-attachments/assets/9994eb37-c22b-4847-9a18-e9acf0ae6236"
/>

<img width="2144" height="1242" alt="CleanShot 2026-01-02 at 09 47
01@2x"
src="https://github.com/user-attachments/assets/9b3bcf39-63f6-4c8d-85c5-2976c25f5b7b"
/>


<img width="2238" height="1632" alt="CleanShot 2026-01-02 at 09 47
17@2x"
src="https://github.com/user-attachments/assets/436433d7-9873-496a-9c96-536e070be9d7"
/>
<img width="1708" height="1260" alt="CleanShot 2026-01-02 at 09 47
23@2x"
src="https://github.com/user-attachments/assets/1ec42402-dbd9-41a3-801b-4745a4f128f7"
/>

---------
Co-authored-by: 's avatarClaude Opus 4.5 <noreply@anthropic.com>
parent f3ccca39
import React from 'react' import React from 'react'
import { errorStyles, errorThemeCss, ErrorIcon } from './error-styles'
const styles: Record<string, React.CSSProperties> = { // This is the static 500.html page for App Router apps.
error: { // Always a server error, rendered at build time.
// https://github.com/sindresorhus/modern-normalize/blob/main/modern-normalize.css#L38-L52
fontFamily:
'system-ui,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"',
height: '100vh',
textAlign: 'center',
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
justifyContent: 'center',
},
desc: {
lineHeight: '48px',
},
h1: {
display: 'inline-block',
margin: '0 20px 0 0',
paddingRight: 23,
fontSize: 24,
fontWeight: 500,
verticalAlign: 'top',
},
h2: {
fontSize: 14,
fontWeight: 400,
lineHeight: '28px',
},
wrap: {
display: 'inline-block',
},
} as const
/* CSS minified from
body { margin: 0; color: #000; background: #fff; }
.next-error-h1 {
border-right: 1px solid rgba(0, 0, 0, .3);
}
@media (prefers-color-scheme: dark) {
body { color: #fff; background: #000; }
.next-error-h1 {
border-right: 1px solid rgba(255, 255, 255, .3);
}
}
*/
const themeCss = `body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}
@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}`
function AppError() { function AppError() {
const errorMessage = 'Internal Server Error.'
const title = `500: ${errorMessage}`
return ( return (
<html id="__next_error__"> <html id="__next_error__">
<head> <head>
<title>{title}</title> <title>500: This page failed to load</title>
<style dangerouslySetInnerHTML={{ __html: errorThemeCss }} />
</head> </head>
<body> <body>
<div style={styles.error}> <div style={errorStyles.container}>
<div style={styles.desc}> <div style={errorStyles.card}>
<style <ErrorIcon />
dangerouslySetInnerHTML={{ <h1 style={errorStyles.title}>This page failed to load</h1>
__html: themeCss, <p style={errorStyles.message}>
}} Something went wrong while loading this page.
/> </p>
<h1 className="next-error-h1" style={styles.h1}> <p style={errorStyles.messageHint}>
500 If this keeps happening, it may be a server issue.
</h1> </p>
<div style={styles.wrap}> <form>
<h2 style={styles.h2}>{errorMessage}</h2> <button type="submit" style={errorStyles.button}>
</div> Reload page
</button>
</form>
</div> </div>
</div> </div>
</body> </body>
......
import React from 'react'
export const errorStyles = {
container: {
fontFamily:
'system-ui,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"',
height: '100vh',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
},
card: {
maxWidth: '420px',
padding: '32px 28px',
textAlign: 'left' as const,
},
icon: {
marginBottom: '16px',
},
title: {
fontSize: '17px',
fontWeight: 600,
letterSpacing: '-0.01em',
margin: '0 0 8px 0',
color: 'var(--next-error-title)',
},
message: {
fontSize: '14px',
fontWeight: 400,
lineHeight: 1.6,
margin: '0 0 6px 0',
color: 'var(--next-error-message)',
},
messageHint: {
fontSize: '13px',
fontWeight: 400,
lineHeight: 1.5,
margin: '0 0 20px 0',
color: 'var(--next-error-hint)',
},
buttonGroup: {
display: 'flex',
gap: '12px',
alignItems: 'center',
},
button: {
padding: '10px 20px',
fontSize: '14px',
fontWeight: 500,
letterSpacing: '0.01em',
borderRadius: '6px',
cursor: 'pointer',
color: 'var(--next-error-btn-text)',
background: 'var(--next-error-btn-bg)',
border: 'var(--next-error-btn-border)',
},
buttonSecondary: {
padding: '10px 20px',
fontSize: '14px',
fontWeight: 500,
letterSpacing: '0.01em',
borderRadius: '6px',
cursor: 'pointer',
color: 'var(--next-error-btn-secondary-text)',
background: 'transparent',
border: 'none',
},
digestContainer: {
marginTop: '20px',
paddingTop: '16px',
borderTop: 'var(--next-error-digest-border)',
},
digest: {
fontSize: '12px',
fontWeight: 400,
margin: '0',
color: 'var(--next-error-digest)',
},
digestCode: {
fontFamily:
'ui-monospace,SFMono-Regular,"SF Mono",Menlo,Consolas,monospace',
fontSize: '11px',
color: 'var(--next-error-digest-code)',
userSelect: 'all' as const,
},
} as const
export const errorThemeCss = `
:root {
--next-error-bg: #fff;
--next-error-text: #171717;
--next-error-title: #171717;
--next-error-message: #666;
--next-error-hint: #888;
--next-error-digest: #999;
--next-error-digest-code: #888;
--next-error-digest-border: 1px solid rgba(0,0,0,0.06);
--next-error-btn-text: #171717;
--next-error-btn-bg: #fff;
--next-error-btn-border: 1px solid #e5e5e5;
--next-error-btn-secondary-text: #666;
--next-error-icon-ring: #fecaca;
--next-error-icon-fill: #fef2f2;
}
@media (prefers-color-scheme: dark) {
:root {
--next-error-bg: #0a0a0a;
--next-error-text: #ededed;
--next-error-title: #ededed;
--next-error-message: #a0a0a0;
--next-error-hint: #707070;
--next-error-digest: #606060;
--next-error-digest-code: #707070;
--next-error-digest-border: 1px solid rgba(255,255,255,0.08);
--next-error-btn-text: #ededed;
--next-error-btn-bg: #1a1a1a;
--next-error-btn-border: 1px solid #333;
--next-error-btn-secondary-text: #a0a0a0;
--next-error-icon-ring: #5c2121;
--next-error-icon-fill: #2a1618;
}
}
body { margin: 0; color: var(--next-error-text); background: var(--next-error-bg); }
`.replace(/\n\s*/g, '')
export function ErrorIcon() {
return (
<svg
width="40"
height="40"
viewBox="0 0 40 40"
fill="none"
style={errorStyles.icon}
>
<circle
cx="20"
cy="20"
r="19"
stroke="var(--next-error-icon-ring)"
strokeWidth="2"
/>
<circle cx="20" cy="20" r="16" fill="var(--next-error-icon-fill)" />
<path
d="M20 12v9"
stroke="#dc2626"
strokeWidth="2.5"
strokeLinecap="round"
/>
<circle cx="20" cy="27" r="1.5" fill="#dc2626" />
</svg>
)
}
'use client' 'use client'
import { HandleISRError } from '../handle-isr-error' import { HandleISRError } from '../handle-isr-error'
import { errorStyles, errorThemeCss, ErrorIcon } from './error-styles'
const styles = {
error: {
// https://github.com/sindresorhus/modern-normalize/blob/main/modern-normalize.css#L38-L52
fontFamily:
'system-ui,"Segoe UI",Roboto,Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"',
height: '100vh',
textAlign: 'center',
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
justifyContent: 'center',
},
text: {
fontSize: '14px',
fontWeight: 400,
lineHeight: '28px',
margin: '0 8px',
},
} as const
export type GlobalErrorComponent = React.ComponentType<{ export type GlobalErrorComponent = React.ComponentType<{
error: any error: any
}> }>
function DefaultGlobalError({ error }: { error: any }) { function DefaultGlobalError({ error }: { error: any }) {
const digest: string | undefined = error?.digest const digest: string | undefined = error?.digest
const isServerError = !!digest
// Server error: "This page failed to load"
// Client error: "This page crashed"
const title = isServerError ? 'This page failed to load' : 'This page crashed'
const message = isServerError
? 'Something went wrong while loading this page.'
: 'An error occurred while running this page.'
const hint = isServerError
? 'If this keeps happening, it may be a server issue.'
: null
return ( return (
<html id="__next_error__"> <html id="__next_error__">
<head></head> <head>
<style dangerouslySetInnerHTML={{ __html: errorThemeCss }} />
</head>
<body> <body>
<HandleISRError error={error} /> <HandleISRError error={error} />
<div style={styles.error}> <div style={errorStyles.container}>
<div> <div style={errorStyles.card}>
<h2 style={styles.text}> <ErrorIcon />
Application error: a {digest ? 'server' : 'client'}-side exception <h1 style={errorStyles.title}>{title}</h1>
has occurred while loading {window.location.hostname} (see the{' '} <p style={errorStyles.message}>{message}</p>
{digest ? 'server logs' : 'browser console'} for more {hint && <p style={errorStyles.messageHint}>{hint}</p>}
information). {!isServerError && (
</h2> <p style={errorStyles.messageHint}>
{digest ? <p style={styles.text}>{`Digest: ${digest}`}</p> : null} Reloading usually fixes this.
</p>
)}
<div style={errorStyles.buttonGroup}>
<form>
<button type="submit" style={errorStyles.button}>
Reload page
</button>
</form>
{!isServerError && (
<button
type="button"
style={errorStyles.buttonSecondary}
onClick={() => {
if (window.history.length > 1) {
window.history.back()
} else {
window.location.href = '/'
}
}}
>
Go back
</button>
)}
</div>
{digest && (
<div style={errorStyles.digestContainer}>
<p style={errorStyles.digest}>
Error reference:{' '}
<code style={errorStyles.digestCode}>{digest}</code>
</p>
</div>
)}
</div> </div>
</div> </div>
</body> </body>
......
...@@ -38,9 +38,7 @@ describe('serialize-circular-error', () => { ...@@ -38,9 +38,7 @@ describe('serialize-circular-error', () => {
`) `)
const bodyText = await browser.elementByCss('body').text() const bodyText = await browser.elementByCss('body').text()
expect(bodyText).toContain( expect(bodyText).toContain('This page crashed')
'Application error: a client-side exception has occurred while loading localhost (see the browser console for more information).'
)
const output = next.cliOutput const output = next.cliOutput
expect(output).toContain( expect(output).toContain(
......
export default function RootLayout({ children }) {
return (
<html>
<body>{children}</body>
</html>
)
}
export default function Home() {
return <div>Home Page</div>
}
import { Suspense } from 'react'
import { connection } from 'next/server'
async function ServerErrorContent() {
await connection()
throw new Error('Test server error')
}
export default function ServerErrorPage() {
return (
<Suspense fallback={<div>Loading...</div>}>
<ServerErrorContent />
</Suspense>
)
}
'use client'
import { useState } from 'react'
export default function TriggerErrorPage() {
const [shouldError, setShouldError] = useState(false)
if (shouldError) {
throw new Error('Test client error')
}
return (
<div>
<h1>Trigger Error Page</h1>
<button id="trigger-error" onClick={() => setShouldError(true)}>
Trigger Error
</button>
</div>
)
}
import { nextTestSetup } from 'e2e-utils'
describe('app dir - default error page UI', () => {
const { next, isNextDev } = nextTestSetup({
files: __dirname,
})
it('should render client error page with correct UI elements', async () => {
const browser = await next.browser('/trigger-error')
// Trigger a client-side error
await browser.elementByCss('#trigger-error').click()
// Skip UI checks in dev mode (redbox overlay covers the error page)
if (isNextDev) {
await expect(browser).toDisplayRedbox(`
{
"description": "Test client error",
"environmentLabel": null,
"label": "Runtime Error",
"source": "app/trigger-error/page.js (9:11) @ TriggerErrorPage
> 9 | throw new Error('Test client error')
| ^",
"stack": [
"TriggerErrorPage app/trigger-error/page.js (9:11)",
],
}
`)
return
}
// In production mode, verify the client error page UI elements
// Check that the SVG icon is present (40x40 size)
const svgIcon = await browser.elementByCss('svg')
expect(await svgIcon.getAttribute('width')).toBe('40')
expect(await svgIcon.getAttribute('height')).toBe('40')
// Check the error title - client errors show "This page crashed"
const title = await browser.elementByCss('h1')
expect(await title.text()).toBe('This page crashed')
// Check the error message - client errors show "An error occurred while running this page."
const message = await browser.elementByCss('p')
expect(await message.text()).toContain('An error occurred while running')
// Check the "Reload page" button exists
const buttons = await browser.elementsByCss('button')
expect(await buttons[0].innerText()).toBe('Reload page')
// Check "Go back" button exists for client errors
expect(await buttons[1].innerText()).toBe('Go back')
// Check the hint text about reloading
const html = await browser.eval('document.documentElement.innerHTML')
expect(html).toContain('Reloading usually fixes this')
})
it('should reload the page when Reload page button is clicked', async () => {
const browser = await next.browser('/trigger-error')
// Trigger a client-side error
await browser.elementByCss('#trigger-error').click()
// Skip in dev mode (redbox overlay)
if (isNextDev) {
return
}
// Get the current URL
const urlBefore = await browser.url()
// Click the Reload page button
await browser.elementByCss('button').click()
// Wait for page to reload (should be back to the trigger-error page)
await browser.waitForElementByCss('#trigger-error')
// Verify we're on the same page
const urlAfter = await browser.url()
expect(urlAfter).toBe(urlBefore)
// Verify the page content is showing (not the error)
const pageTitle = await browser.elementByCss('h1')
expect(await pageTitle.text()).toBe('Trigger Error Page')
})
it('should have proper styling in the default error page', async () => {
const browser = await next.browser('/trigger-error')
// Trigger a client-side error
await browser.elementByCss('#trigger-error').click()
// Skip in dev mode
if (isNextDev) {
return
}
// Check that the title has neutral dark color (not red)
const title = await browser.elementByCss('h1')
const titleColor = await title.getComputedCss('color')
// In light mode: #171717 = rgb(23, 23, 23)
expect(titleColor).toContain('23')
// Check that the button has neutral styling (white background with border)
const button = await browser.elementByCss('button')
const buttonBg = await button.getComputedCss('background-color')
// White = rgb(255, 255, 255)
expect(buttonBg).toContain('255')
})
it('should display server error page with Error reference', async () => {
const browser = await next.browser('/server-error')
// Skip in dev mode (redbox overlay)
if (isNextDev) {
await expect(browser).toDisplayRedbox(`
{
"description": "Test server error",
"environmentLabel": "Server",
"label": "Runtime Error",
"source": "app/server-error/page.js (6:9) @ ServerErrorContent
> 6 | throw new Error('Test server error')
| ^",
"stack": [
"ServerErrorContent app/server-error/page.js (6:9)",
],
}
`)
return
}
// In production mode, verify the server error page
const html = await browser.eval('document.documentElement.innerHTML')
// Server errors show "This page failed to load"
expect(html).toContain('This page failed to load')
// Server errors show "Error reference:" with digest
expect(html).toContain('Error reference:')
// Server errors show hint about server issue
expect(html).toContain('it may be a server issue')
})
it('should have left-aligned text in error page', async () => {
const browser = await next.browser('/trigger-error')
await browser.elementByCss('#trigger-error').click()
if (isNextDev) {
return
}
// Check that the h1 has left text alignment
const title = await browser.elementByCss('h1')
const textAlign = await title.getComputedCss('text-align')
expect(textAlign).toBe('left')
})
})
...@@ -189,10 +189,8 @@ describe('app-dir - errors', () => { ...@@ -189,10 +189,8 @@ describe('app-dir - errors', () => {
`) `)
} else { } else {
expect( expect(
await browser.waitForElementByCss('body').elementByCss('h2').text() await browser.waitForElementByCss('body').elementByCss('h1').text()
).toBe( ).toBe('This page crashed')
'Application error: a client-side exception has occurred while loading localhost (see the browser console for more information).'
)
} }
expect(pageErrors).toEqual([ expect(pageErrors).toEqual([
...@@ -228,13 +226,11 @@ describe('app-dir - errors', () => { ...@@ -228,13 +226,11 @@ describe('app-dir - errors', () => {
`) `)
} else { } else {
expect( expect(
await browser.waitForElementByCss('body').elementByCss('h2').text() await browser.waitForElementByCss('body').elementByCss('h1').text()
).toBe( ).toBe('This page failed to load')
'Application error: a server-side exception has occurred while loading localhost (see the server logs for more information).' // Check digest is displayed in error reference
) const bodyText = await browser.waitForElementByCss('body').text()
expect( expect(bodyText).toMatch(/Error reference:\s*\w+/)
await browser.waitForElementByCss('body').elementByCss('p').text()
).toMatch(/Digest: \w+/)
} }
expect(pageErrors).toEqual([ expect(pageErrors).toEqual([
......
...@@ -31,10 +31,10 @@ describe('app dir - global-error - error-in-global-error', () => { ...@@ -31,10 +31,10 @@ describe('app dir - global-error - error-in-global-error', () => {
it('should render fallback UI when error occurs in global-error', async () => { it('should render fallback UI when error occurs in global-error', async () => {
const browser = await next.browser('/?error-in-global-error=1') const browser = await next.browser('/?error-in-global-error=1')
const text = await browser.elementByCss('h2').text() // When the custom global-error throws, it falls back to the default global-error
expect(text).toMatch( // Client errors show "This page crashed"
/Application error: a client-side exception has occurred while loading [\w.-]+ \(see the browser console for more information\)./ const title = await browser.elementByCss('h1').text()
) expect(title).toBe('This page crashed')
if (isNextDev) { if (isNextDev) {
await waitForRedbox(browser) await waitForRedbox(browser)
......
...@@ -36,7 +36,7 @@ describe('revalidateTag-rsc', () => { ...@@ -36,7 +36,7 @@ describe('revalidateTag-rsc', () => {
await retry(async () => { await retry(async () => {
expect( expect(
await browser.eval('document.documentElement.innerHTML') await browser.eval('document.documentElement.innerHTML')
).toContain('Application error: a server-side exception has occurred') ).toContain('This page failed to load')
}) })
} }
......
...@@ -28,8 +28,9 @@ describe('next-link', () => { ...@@ -28,8 +28,9 @@ describe('next-link', () => {
} }
`) `)
} }
expect(await browser.elementByCss('body').text()).toMatchInlineSnapshot( // Client errors show "This page crashed"
`"Application error: a client-side exception has occurred while loading localhost (see the browser console for more information)."` expect(await browser.elementByCss('body').text()).toContain(
'This page crashed'
) )
}) })
...@@ -51,8 +52,9 @@ describe('next-link', () => { ...@@ -51,8 +52,9 @@ describe('next-link', () => {
], ],
} }
`) `)
expect(await browser.elementByCss('body').text()).toMatchInlineSnapshot( // Client errors show "This page crashed"
`"Application error: a client-side exception has occurred while loading localhost (see the browser console for more information)."` expect(await browser.elementByCss('body').text()).toContain(
'This page crashed'
) )
} else { } else {
expect(await browser.elementByCss('body').text()).toMatchInlineSnapshot( expect(await browser.elementByCss('body').text()).toMatchInlineSnapshot(
......
...@@ -11,8 +11,8 @@ describe('500-page app-router-only', () => { ...@@ -11,8 +11,8 @@ describe('500-page app-router-only', () => {
it('should render app router 500 page when route error', async () => { it('should render app router 500 page when route error', async () => {
const $ = await next.render$('/route-error') const $ = await next.render$('/route-error')
expect($('html').attr('id')).toBe('__next_error__') expect($('html').attr('id')).toBe('__next_error__')
expect($('body').text()).toContain('Internal Server Error.') // Server errors show "This page failed to load"
expect($('body').text()).toContain('500') expect($('body').text()).toContain('This page failed to load')
}) })
} }
...@@ -24,7 +24,8 @@ describe('500-page app-router-only', () => { ...@@ -24,7 +24,8 @@ describe('500-page app-router-only', () => {
) )
// Not use pages router to generate 500.html // Not use pages router to generate 500.html
expect(html).toContain('__next_error__') expect(html).toContain('__next_error__')
expect(html).toContain('Internal Server Error.') // Server errors show "This page failed to load"
expect(html).toContain('This page failed to load')
// global-error is not used in app router 500.html // global-error is not used in app router 500.html
expect(html).not.toContain('app-router-global-error') expect(html).not.toContain('app-router-global-error')
}) })
......
...@@ -32,9 +32,8 @@ describe('graceful-degrade - non bot', () => { ...@@ -32,9 +32,8 @@ describe('graceful-degrade - non bot', () => {
expect(await body.getAttribute('class')).not.toBe('body-cls') expect(await body.getAttribute('class')).not.toBe('body-cls')
const bodyText = await body.text() const bodyText = await body.text()
expect(bodyText).toMatch( // Client errors show "This page crashed"
/Application error: a client-side exception has occurred while loading/ expect(bodyText).toMatch(/This page crashed/)
)
}) })
it('should show error boundary when browser errors when error boundary is defined', async () => { it('should show error boundary when browser errors when error boundary is defined', async () => {
......
...@@ -31,9 +31,7 @@ describe('graceful-degrade', () => { ...@@ -31,9 +31,7 @@ describe('graceful-degrade', () => {
// Do not contain the global error boundary text // Do not contain the global error boundary text
const bodyText = await originBody.text() const bodyText = await originBody.text()
expect(bodyText).not.toMatch( expect(bodyText).not.toMatch(/This page crashed/)
/Application error: a client-side exception has occurred while loading/
)
}) })
it('should preserve the ssr html when browser errors for bot', async () => { it('should preserve the ssr html when browser errors for bot', async () => {
...@@ -50,9 +48,7 @@ describe('graceful-degrade', () => { ...@@ -50,9 +48,7 @@ describe('graceful-degrade', () => {
expect(errors).toMatch(/Error: boom/) expect(errors).toMatch(/Error: boom/)
const bodyText = await browser.elementByCss('body').text() const bodyText = await browser.elementByCss('body').text()
expect(bodyText).not.toMatch( expect(bodyText).not.toMatch(/This page crashed/)
/Application error: a client-side exception has occurred while loading/
)
expect(bodyText).toMatch(/fine/) expect(bodyText).toMatch(/fine/)
}) })
}) })
...@@ -41,9 +41,8 @@ describe('chunk-load-failure', () => { ...@@ -41,9 +41,8 @@ describe('chunk-load-failure', () => {
await retry(async () => { await retry(async () => {
const body = await browser.elementByCss('body') const body = await browser.elementByCss('body')
expect(await body.text()).toMatch( // Client errors show "This page crashed"
/Application error: a client-side exception has occurred while loading/ expect(await body.text()).toMatch(/This page crashed/)
)
}) })
expect(pageError).toBeDefined() expect(pageError).toBeDefined()
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment