Troubleshoot WebContainer and LiveStack preview

Identify which preview runtime failed

The frontend WebContainer runs in desktop Chrome or Edge on your device. It consumes local CPU, RAM, browser storage and network bandwidth. LiveStack backend modules run as verified artifacts in an isolated BlinkHost preview environment. Neither runtime changes production until you publish and deploy.

Symptom	Most likely boundary	What to inspect
WebContainer boot or tab crash	Browser or device	Browser support, free memory, extensions, power mode
Mounting or dependency installation is slow	Workspace, browser storage or network	Large files, lockfile, network and visible stage
Frontend build or start command fails	Project scripts and dependencies	First actionable output, expected port, process exit
Backend Build fails	Module source, supported dependency or compiler	First compiler error and build ID
LiveStack session cannot start	Verified artifact, session admission or platform availability	Module artifact state and session message
Backend preview is not connected	Session or capability bridge	Frontend Ready state, LiveStack Ready state, then reload preview once
Module returns missing database or secret	Resource binding	Exact preview binding or secret name and scope
Preview email does not reach an inbox	Expected preview behavior	Inspect the IDE email sink; preview email is never delivered
Preview works but deployed site fails	Production release or runtime	Deployment and production telemetry, not preview restart

Recover in order

1. Preserve work and wait for the current save to complete.
2. Record the visible stage, UTC time and first useful diagnostic.
3. For browser startup, close memory-heavy tabs, confirm the network and restart WebContainer once.
4. For a module build, fix the first compiler or validation error. Unchanged verified source can reuse its artifact.
5. For LiveStack, confirm the frontend is Ready, select a verified module artifact, then start or restart one session.
6. Confirm every required database uses a development/preview binding and every required secret has a development/preview scope.
7. Test a minimal project to separate device health from project-specific complexity.

Do not repeatedly deploy to test a browser or LiveStack-only failure. Do not insert production credentials to work around a missing preview resource.

Escalate with project ID, module/build ID when relevant, browser and version, device RAM for WebContainer issues, visible stage, diagnostic and UTC time. Never send passwords, cookies, capability tokens, secret values, database credentials or customer data.

Astro first-start timing

Astro may need longer than other starters on its first run because the browser must prepare dependencies and the development server. BlinkHost allows up to five minutes for this first Astro start and shows the current stage while it waits. Later starts are normally faster because the browser can reuse local caches.

Keep the IDE tab active, prevent the device from sleeping and allow the current stage to finish. On a low-memory device, close other heavy tabs before retrying. If no stage changes before the visible timeout, preserve the saved workspace, copy the first actionable output and restart the WebContainer once. Repeated restarts discard useful progress and usually make a slow dependency download take longer.

If the server starts but the page does not render, check the configured development command, the port reported by the process and the first application error. A browser-side timeout does not publish or alter the deployed site.

Faster repeat starts

BlinkHost begins preparing the browser runtime while project data loads. It keeps an idle runtime briefly during normal navigation, synchronizes only changed workspace files when returning to the same project, and reuses dependency state only when the package manifest and lockfile fingerprint still match.

Commit the package-manager lockfile for your project. Locked installs are deterministic, disable package lifecycle scripts and prefer the browser's safe package cache. BlinkHost does not share a project's installed dependency directory with another project.

The IDE records bounded timings for runtime boot, workspace synchronization, dependency installation and preview readiness. These measurements contain no source code, filenames, dependency names or secret values and help BlinkHost identify slow preview stages across browser and network conditions.