How to fix Unhandled error thrown by lazy-loaded component in React

ReactINTERMEDIATEHIGH

When using React.lazy() for code splitting, errors during chunk loading or component initialization are not caught unless wrapped in an Error Boundary. This leads to unhandled promise rejections and white-screen failures.

What this error means

React.lazy() enables code splitting by asynchronously loading component chunks. When the Promise rejects—due to network failures, missing chunks, or component errors—React throws the error for the nearest Error Boundary to handle. Without an Error Boundary, unhandled errors will crash your application with no graceful fallback. Error Boundaries are class components (or hooks wrappers) that catch errors thrown in child components. For lazy-loaded components, they catch both chunk-loading failures and rendering errors that occur after the component loads.

How to fix "Unhandled error thrown by lazy-loaded component"

1Create a class-based Error Boundary component

Error Boundaries must be class components. Create one to wrap your lazy components:

typescript

import React from 'react';

interface ErrorBoundaryProps {
  children: React.ReactNode;
}

interface ErrorBoundaryState {
  hasError: boolean;
  error: Error | null;
}

class ErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
  constructor(props: ErrorBoundaryProps) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    console.error('Error caught by boundary:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return (
        <div style={{ padding: '20px' }}>
          <h2>Something went wrong</h2>
          <p>{this.state.error?.message || 'Failed to load this component'}</p>
        </div>
      );
    }

    return this.props.children;
  }
}

export default ErrorBoundary;

2Wrap lazy components with ErrorBoundary above Suspense

Always place ErrorBoundary outside (above) your Suspense component to catch both loading and rendering errors:

typescript

import React, { Suspense } from 'react';
import ErrorBoundary from './ErrorBoundary';

// Lazy load a component
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));

function App() {
  return (
    <ErrorBoundary>
      <Suspense fallback={<div>Loading...</div>}>
        <HeavyComponent />
      </Suspense>
    </ErrorBoundary>
  );
}

export default App;

The nesting order is critical: ErrorBoundary → Suspense → Lazy component.

3Handle lazy loading errors specifically with enhanced fallback

You can create a specialized error boundary for lazy routes that provides better feedback:

typescript

class LazyErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
  constructor(props: ErrorBoundaryProps) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    // Check if this is a chunk loading error
    const isChunkLoadError = /loading chunk/.test(error.message);
    return { hasError: true, error, isChunkLoadError };
  }

  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
    if (/loading chunk/.test(error.message)) {
      console.error('Chunk loading failed:', error);
    } else {
      console.error('Component error:', error);
    }
  }

  render() {
    if (this.state.hasError) {
      return (
        <div style={{ padding: '40px', textAlign: 'center' }}>
          <h2>Failed to load this page</h2>
          <p>{this.state.error?.message}</p>
          <button onClick={() => window.location.reload()}>
            Reload page
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

4Create granular error boundaries for different sections

Instead of one global error boundary, create multiple boundaries at different levels to isolate failures:

typescript

function Dashboard() {
  const UserPanel = React.lazy(() => import('./UserPanel'));
  const Analytics = React.lazy(() => import('./Analytics'));
  const Settings = React.lazy(() => import('./Settings'));

  return (
    <div>
      <header>My Dashboard</header>

      <ErrorBoundary>
        <Suspense fallback={<Skeleton />}>
          <UserPanel />
        </Suspense>
      </ErrorBoundary>

      <ErrorBoundary>
        <Suspense fallback={<LoadingSpinner />}>
          <Analytics />
        </Suspense>
      </ErrorBoundary>

      <ErrorBoundary>
        <Suspense fallback={<LoadingSpinner />}>
          <Settings />
        </Suspense>
      </ErrorBoundary>
    </div>
  );
}

This way, if one lazy section fails, the others still render normally.

5Verify error boundary is working with error simulation

Test your error boundary during development to ensure it catches errors properly:

typescript

// In your lazy component, simulate an error
const HeavyComponent = () => {
  // Force an error during development
  if (process.env.NODE_ENV === 'development' && Math.random() > 0.99) {
    throw new Error('Test error from lazy component');
  }

  return <div>Component loaded successfully</div>;
};

export default HeavyComponent;

// Or test the boundary with this pattern
function TestError() {
  const [shouldError, setShouldError] = React.useState(false);

  if (shouldError) {
    throw new Error('Intentional test error');
  }

  return (
    <div>
      <button onClick={() => setShouldError(true)}>
        Trigger Error
      </button>
    </div>
  );
}

How to fix Unhandled error thrown by lazy-loaded component in React

What this error means

Typical symptoms

Common causes

How to fix "Unhandled error thrown by lazy-loaded component"

Advanced notes

Related errors

Official resources & further reading