PromptHub
Back to Errors
Frontend Intermediate 250 views

ChunkLoadError

A dynamically imported JavaScript chunk failed to load from the server.

Explanation

ChunkLoadError occurs when the browser cannot load a dynamically imported JavaScript chunk (code-split bundle). This is common in React, Vue, and other modern frameworks that use code splitting to lazy-load components. The error typically shows the URL of the chunk that failed to load. Common causes include deploying a new version while users have the old version open (chunk hash mismatch), CDN or server issues, network failures, or the chunk file not being deployed properly.

Common Causes

  • New deployment invalidating old chunk hashes
  • CDN or server serving stale chunks
  • Network failure during chunk load
  • Chunk file not in build output
  • Aggressive caching without hash busting

Solution

Implement error boundaries to catch chunk loading failures and show a fallback UI. Add retry logic for failed chunk loads. Ensure all chunks are deployed when releasing new versions. Configure your server to serve index.html for unknown routes (SPA fallback). Use a CDN with proper caching headers. Check that the build output includes all expected chunks. Implement a version check mechanism that prompts users to reload when a new version is available. Set appropriate cache-control headers for chunk files.

Code Example 

// React lazy loading with error boundary
const LazyComponent = React.lazy(() => import('./HeavyComponent'));

function App() {
    return (
        <ErrorBoundary fallback={<div>Failed to load. <button onClick={() => window.location.reload()}>Reload</button></div>}>
            <Suspense fallback={<div>Loading...</div>}>
                <LazyComponent />
            </Suspense>
        </ErrorBoundary>
    );
}

// Vue lazy loading
const LazyComponent = () => import('./HeavyComponent.vue');

// Retry logic for chunk loading
async function loadChunk(importFn, retries = 3) {
    try {
        return await importFn();
    } catch (error) {
        if (retries > 0 && error.name === 'ChunkLoadError') {
            await new Promise(r => setTimeout(r, 1000));
            return loadChunk(importFn, retries - 1);
        }
        throw error;
    }
}

// Nginx configuration for SPA
location / {
    try_files $uri $uri/ /index.html;
}

// Cache control for chunks
location /static/js/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Error Information

Language

javascript

Difficulty

Intermediate

Views

250

Related Errors

Frontend

WebSocket Connection Failed

The WebSocket connection could not be established or was closed unexpectedly.
Frontend

Hydration Mismatch (SSR)

The server-rendered HTML doesn't match what the client-side JavaScript expected to render.
ENOENT Node.js

ENOENT: No Such File or Directory

The operating system cannot find the specified file or directory.
Frontend

Invalid DOM Property

The code uses an incorrect HTML attribute or React-specific prop on a DOM element.
All tools