Imported from jeremylongshore/tons-of-skills-marketplace (
plugins/saas-packs/stackblitz-pack/skills/stackblitz-common-errors/SKILL.md). Install upstream withnpx skills add jeremylongshore/tons-of-skills-marketplace --skill stackblitz-common-errors. Copyright stays with the author (MIT).
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.