Customize error message

[AllureWang]

Summary

When the network condition is poor and the chunk files are not completely downloaded, an error will occur on the page: "Application error: a client-side exception has occurred (see the browser console for more information)." How can we customize error message?

Additional information

No response

Example

No response

[weyniis]

I've seen this issue happen when there's a network problem or slow connection, and the JS bundle (chunk file) fails to load. What u're seeing:

"Application error: a client-side exception has occurred..."

is actually the default fallback screen shown by Vercel or the React production error overlay.

---

✅ Here's what u can do to customize the message or make the error more user-friendly:

1. Wrap your app in a custom ErrorBoundary

Create a global error boundary to catch unexpected errors and show a custom UI.

// components/ErrorBoundary.tsx
import React from "react";

class ErrorBoundary extends React.Component {
state = { hasError: false };

static getDerivedStateFromError(error: any) {
return { hasError: true };
}

componentDidCatch(error: any, info: any) {
console.error("Caught by ErrorBoundary:", error, info);
}

render() {
if (this.state.hasError) {
return

Something went wrong. Please refresh the page or try again later.

;
}

return this.props.children;

}
}

export default ErrorBoundary;

Then wrap your _app.tsx like this:

// pages/_app.tsx
import ErrorBoundary from "@/components/ErrorBoundary";

function MyApp({ Component, pageProps }) {
return (

<Component {...pageProps} />

);
}

export default MyApp;

---

2. Add a custom 500 error page (for server-side fallback)

If chunk loading fails and throws a hard crash, having a 500 page helps fallback gracefully:

// pages/500.tsx
export default function Custom500() {
return (
<div style={{ padding: "2rem", textAlign: "center" }}>

Oops, something went wrong!

This may be a network issue. Try refreshing the page.

);
}

---

3. Use window.onerror to catch chunk load errors

If u want to handle chunk load failure specifically, you can register an event listener:

if (typeof window !== "undefined") {
window.addEventListener("error", function (e) {
if (e?.message?.includes("ChunkLoadError")) {
alert("Network error occurred. Please try refreshing.");
}
});
}

---

📌 Summary:

• Add a global ErrorBoundary to customize unexpected errors
• Provide a fallback pages/500.tsx to improve UX
• Catch and respond to chunk load failures in client

[AllureWang]

I have added the ErrorHandlerFeature in the root node's layout and set up an error event listener. However, during testing, there is still a chance that the original error page is displayed instead of the custom one. I suspect this happens when the JS file handling errors is not successfully returned.