Troubleshoot WebContainer and LiveStack preview
Separate device-side frontend startup from remote module build, session and resource failures.
Last updated 2026-09-02
What you'll achieve
- Identify the stage slowing preview startup
- Use deterministic dependency installs
- Recover a preview without losing saved work
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
- Preserve work and wait for the current save to complete.
- Record the visible stage, UTC time and first useful diagnostic.
- For browser startup, close memory-heavy tabs, confirm the network and restart WebContainer once.
- For a module build, fix the first compiler or validation error. Unchanged verified source can reuse its artifact.
- For LiveStack, confirm the frontend is Ready, select a verified module artifact, then start or restart one session.
- Confirm every required database uses a development/preview binding and every required secret has a development/preview scope.
- 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.
Work safely while the browser runtime is active
The IDE writes rapid editor changes to the browser runtime in small batches and flushes the newest file state before every production build or artifact package. Saving to BlinkHost and synchronizing with the local preview are separate signals: check Saved for the remote workspace and Preview ready for the browser environment.
If the network disconnects, keep editing in the current tab. Saving, dependency installation, builds and publishing resume only after the browser reconnects. Do not close or reload the tab until the project reports Saved.
Open Output with Ctrl+** or **Command+. Build, install, preview and system output have separate tabs and can be filtered or copied for support. The status bar opens the relevant output when selected and shows the connected Git branch, active file type and detected frontend directory.
Recover without losing saved source
Choose Restart when the preview process stopped but dependencies are still valid. Choose Refresh dependencies when installation state is damaged or the package manifest and lockfile changed unexpectedly. Refreshing dependencies clears only the reusable installation fingerprint and starts a deterministic install; it does not delete project source. Use it only after reviewing Install output because a clean install takes longer.
On a lower-memory device, close unrelated browser tabs before starting a large framework preview. If browser preview remains incompatible, preserve the source, use the repository build path and review the exact managed-build result instead of repeatedly restarting the browser.
Help improve this page
Sign in to send page-specific feedback. For account-specific help, email support@blinkhost.me.