stackblitz-common-errors

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

• WebContainer API Reference
• Browser Compatibility

Next Steps

For debugging, see stackblitz-debug-bundle.