Troubleshooting
Diagnose common boot, Service Worker, install, process, and preview problems.
The page is not cross-origin isolated
Check window.crossOriginIsolated. If it is false:
- Confirm the HTML response includes COOP and COEP headers.
- Confirm workers, WebAssembly, fonts, and third-party scripts comply with the selected COEP policy.
- Check that a proxy or hosting layer did not remove the headers.
The Service Worker cannot control the preview
Confirm your application uses startpod/vite or startpod/next and the host
page is cross-origin isolated. In your browser's network panel, check that the
managed preview's Service Worker loaded successfully.
After changing a Service Worker during development, close other tabs for the origin, unregister stale workers in browser developer tools, and reload once.
If Startpod reports ERR_SP_ROOT_SERVICE_WORKER_CONFLICT, you have opted into
same-origin previews and your application already owns the root Service Worker
scope. Remove the same-origin opt-in to use Startpod's managed preview.
npm install cannot reach the registry
Inspect the install process output. Private registries and authenticated package installs are not supported yet.
A command fails immediately
Request the matching packaged worker under /__startpod/workers/:
- Node.js files need
processWorkerUrl. - Shells need
shellWorkerUrl. - Vite and Next.js need
genericWorkerUrl. - Plain HTTP servers need
nodeServerWorkerUrl. - Next.js also needs its fork, worker-thread, and SWC assets.
The framework integration serves all package-owned workers. A missing file usually means the integration did not run during the host build.
No preview appears
Call mountPreview() before spawning the dev server, and keep the process alive. If you call requestPreview() too early, Startpod returns ERR_SP_PREVIEW_NOT_READY.
A second boot fails
A page can have one live pod. Call teardown() on the current pod before booting a replacement.
Collect useful diagnostics
Record the error code, browser version, crossOriginIsolated value, selected COEP mode, command and arguments, process output, and the smallest project that reproduces the problem. Do not include API keys, registry credentials, or project secrets.