09. A lazy-loaded component fails to load. How should the UI behave?
Short answer
Suspense only handles waiting. A failed import() throws an error that must be caught by an Error Boundary placed around the Suspense boundary. The UI should show a small, local error with a Retry button (not a blank page), retry transient network failures automatically a couple of times, and, if the chunk is missing because a new version was deployed, offer a full page reload. Note that React.lazy caches the rejected result, so a real retry needs a fresh lazy() instance.
Why it happens
lazy(() => import("./Chart"))
├─ pending → nearest <Suspense> shows fallback
├─ resolved → render Chart
└─ rejected → error thrown during render → nearest Error Boundary
(no boundary → React unmounts the whole root → blank screen)
Common causes:
- Flaky or offline network on mobile.
- Deploy skew: the user's old HTML references
chunk-abc123.js, which the new deploy removed (ChunkLoadError/ "Failed to fetch dynamically imported module"). - Ad blockers or CDN errors.
Resetting the Error Boundary alone isn't enough. The same lazy object re-throws its cached error, so the retry has to call import() again.
How to fix it
- Wrap the lazy component in an Error Boundary + Suspense pair, close to the widget.
- Retry the import automatically with backoff.
- On manual retry, recreate the lazy component.
- For chunk errors after a deploy, suggest reloading (guarded, so you don't loop).
import { lazy, Suspense, useState } from "react";
import { ErrorBoundary } from "react-error-boundary";
function retryImport(factory, retries = 2, delay = 500) {
return factory().catch((err) =>
retries > 0
? new Promise((r) => setTimeout(r, delay)).then(() =>
retryImport(factory, retries - 1, delay * 2)
)
: Promise.reject(err)
);
}
const loadReport = () => retryImport(() => import("./ReportViewer"));
export default function ReportSection() {
// Kept in state so a manual retry can swap in a brand-new lazy instance
const [Report, setReport] = useState(() => lazy(loadReport));
return (
<ErrorBoundary
onReset={() => setReport(() => lazy(loadReport))}
fallbackRender={({ error, resetErrorBoundary }) => {
const isChunkError = /dynamically imported module|ChunkLoadError|Loading chunk/i.test(error.message);
return (
<div role="alert">
<p>We couldn't load the report.</p>
{isChunkError ? (
<button onClick={() => window.location.reload()}>Reload page (new version available)</button>
) : (
<button onClick={resetErrorBoundary}>Retry</button>
)}
</div>
);
}}
>
<Suspense fallback={<ReportSkeleton />}>
<Report />
</Suspense>
</ErrorBoundary>
);
}
⚠️ Gotcha: Error Boundaries don't catch errors in event handlers or async code outside rendering. They do catch lazy and
use()rejections, because those surface during render.
💡 Interview tip: Mention prevention, too: keep old chunks on the CDN for a while after a deploy, and prefetch critical chunks on hover or idle so failures happen less often.
How to verify
- DevTools → Network → block the chunk's URL: the local error UI appears and the rest of the app keeps working.
- Unblock and click Retry: a new request fires and the component renders.
- Simulate offline mode, then go online: the automatic retries recover.
- Log errors from the boundary's
onErrorto your monitoring tool (e.g. Sentry).
Follow-up questions
- Why not catch the error inside the lazy factory and return a fallback component? You can (
.catch(() => ({ default: ErrorStub }))), but then you lose the boundary's reset flow and error reporting. - Where should the boundary go? Around the feature, not the root; a failed chart shouldn't take down navigation.
- What about Next.js?
error.jsfiles are route-level Error Boundaries with areset()function;next/dynamicbuilds onlazy.
Quick recap
- Suspense handles loading; an Error Boundary handles failure.
- Show local, actionable error UI with Retry.
lazycaches rejections, so recreate it (or retry inside the factory).- Reload for deploy-skew chunk errors, guarded against loops.