StackBlitz Common Errors

Error Reference

SharedArrayBuffer is not defined

Cause: Missing cross-origin isolation headers.

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

Fix: Add both headers to your server. In Vite: server.headers config.

Failed to boot WebContainer

Cause: Only one WebContainer instance allowed per page.

// BAD: Multiple boot calls
const wc1 = await WebContainer.boot();
const wc2 = await WebContainer.boot(); // Fails!

// GOOD: Singleton pattern
let instance: WebContainer | null = null;
async function getWC() {
  if (!instance) instance = await WebContainer.boot();
  return instance;
}

npm install hangs or fails

Cause: Large dependency tree or network issue in WebContainer.

// Use --prefer-offline and minimal deps
const proc = await wc.spawn('npm', ['install', '--prefer-offline']);
const code = await proc.exit;
if (code !== 0) {
  console.error('Install failed, retrying...');
  const retry = await wc.spawn('npm', ['install']);
  await retry.exit;
}

server-ready event never fires

Cause: Application not listening on a port.

// Ensure your app calls listen()
// app.listen(3000) -- required for server-ready event
// Also check process exit code for crashes
wc.on('error', (err) => console.error('WC error:', err));

File operations fail with ENOENT

Cause: Parent directory doesn't exist.

// Create parent directories first
await wc.fs.mkdir('/src/components', { recursive: true });
await wc.fs.writeFile('/src/components/Button.tsx', content);

Quick Diagnostic

// Check WebContainer state
async function diagnose(wc: WebContainer) {
  try {
    await wc.fs.readdir('/');
    console.log('FS: OK');
  } catch { console.error('FS: FAILED'); }

  try {
    const proc = await wc.spawn('node', ['-v']);
    await proc.exit;
    console.log('Node: OK');
  } catch { console.error('Node: FAILED'); }
}

Error Handling

Error	Retryable	Action
Missing COOP/COEP	No	Fix server headers
Multiple boot	No	Use singleton pattern
npm install fail	Yes	Retry once, then report
ENOENT	No	Create parent dirs
Process crash	Yes	Restart process

Resources

Next Steps

For debugging, see stackblitz-debug-bundle.