Fix a Dev Preview
What to do when a Dev Preview does not work: a slow or stuck start, a crash loop, a server that will not stop, live reload that died, certificate and connection errors, a crashed page, and navigation or sign-in Daintree blocked on purpose.
When it goes wrong
Slow or stuck startup
Daintree waits for the dev server to respond before showing the preview. The wait window is the Load timeout in project settings, 1 to 120 seconds (default 30). Daintree does not restart a slow server on its own; it escalates in stages so you can decide:
- After 6 seconds: an ambient working indicator on the panel. No banner
- After 15 seconds with no URL and no sign of compiling, the drawer opens so the server's own output is in view
- After 20 seconds: a warning banner, Dev server is slow to start, with a Restart dev server button, noting that restarting clears the logs you may want to read first. Suppressed if the server has reported that it is compiling: a compile is a signal, not a stall
- After 45 seconds: an error banner, Dev server still hasn't started. If the server logged a recognizable error, the banner shows it and offers the matching remedy (Restart and clear cache, or Reinstall dependencies) with a plain restart in the overflow. Otherwise it names the likely causes: the port is still bound, dependencies are missing, or the build cache is stuck. If the server is still compiling, the title switches to First compile is taking longer than usual instead
The timers reset the moment the server leaves the Starting state, and the Installing state suppresses them, so a long first-run install doesn't trigger a false warning. The Diagnostics tab records each readiness attempt and what it saw, which usually says whether the server never bound its port or answered with an error.
Crash loops
A broken configuration (missing dependencies that an install can't fix) would otherwise drive an unbounded install-crash-reinstall cycle that burns CPU and battery. A guard counts consecutive fast crashes and backs off geometrically between attempts, starting at 500ms, multiplying by 1.5, capped at 3 seconds. After 5 attempts it stops respawning and leaves the session stopped, with a Dev server stopped banner ("The server crashed and restarted several times in a row") and a Restart dev server button for once you've fixed the config. A server that stays up for 5 seconds graduates and resets the counter, so fixing the bug is not punished by a long wait. Every step is recorded in the Diagnostics timeline.
A server that won't stop
If a dev server ignores the stop signal, Daintree terminates it after 5 seconds and says so with a Dev server was force-quit banner. If it is still running after that, the panel shows an error, Dev server didn't stop within 8s. Stop it again, or close the project to retry., and keeps tracking the process, so a later start does not launch a second server beside it. The Running processes view lists it too.
A stop you asked for also stays in effect across remounts, hibernation and a relaunch. If a preview you expected to come back shows Start the dev server, that is why: press Start dev server. See Stops that stick.
Live reload has silently died
A custom server.hmr.* config can point Vite's browser socket somewhere that isn't reachable from the proxy origin. The dev server keeps logging [vite] hmr update on every save (which reads as "live reload is working") while the page never updates. Daintree matches Vite's own HMR failure messages in the console stream and raises a Live reload disconnected banner with a Reload button, so a stale preview is visible rather than confusing.
Certificate and connection errors
A failed page load replaces the preview with a named error rather than a blank pane: Dev server unreachable, Dev server unavailable, Page load timed out, Couldn't resolve address, Certificate error, No internet connection, Load cancelled or Page load failed. A certificate error adds a Copy mkcert -install button, which can help when the server uses an mkcert certificate and its local CA is not installed. Certificate name mismatches and expired certificates require fixing the server certificate. Unreachable and unavailable servers offer Restart dev server with More restart options beside it; other failures offer Retry. Every error offers Open in external browser once the page has an address.
On a plain connection-refused or connection-reset, Daintree first retries up to 5 times with exponential backoff from 500ms up to 8 seconds, showing "Reconnecting (attempt N of 5)…". That covers the common race where the dev server announces itself as ready a moment before it is actually reachable. When the proxy itself reports that the server is down (Dev server unavailable, usually mid-restart), the preview reloads on its own up to 5 times, waiting from 1 second up to 16 seconds between tries, then asks you to restart or reload.
In a window on a remote host, the dev server runs on the host and the preview reaches it through a port forwarded to this machine, listed as Dev preview in the Ports view. If the whole window shows the connection as lost, see Connection States.
The page crashed or stopped responding
If the preview's renderer process dies, a Preview process crashed banner names the reason and exit code and offers Reload, with Hard restart in the overflow. If the page stops responding (usually a long-running script), a Preview is not responding banner appears with the same hard-restart escape. Both are dismissible.
Blocked external navigation
The preview only shows pages on your dev server. If a page in it navigates or redirects off localhost, Daintree stops the navigation and shows a banner naming where it was going: Can't open host here, with the full hostname and the URL beneath it, or Can't open scheme links here for a link such as slack://. From the banner you can Open in external browser (Open in default app for a non-web link) or Copy URL, or dismiss it. Links that open a new window, target="_blank" or window.open(), go straight to your default browser instead.
OAuth sign-in
When the blocked URL looks like an OAuth flow, the banner reads Can't show the host sign-in here and offers Sign in via browser instead. That runs a loopback sign-in: you sign in through your real browser, Daintree intercepts the token exchange, and the session comes back to the embedded page, so you stay in the preview rather than ending up signed in only in a separate browser. The identity provider must accept the temporary http://127.0.0.1:<port>/oauth/callback redirect; providers restricted to a fixed callback can reject it. The same happens when the page opens its sign-in in a popup.
While it waits, the banner reads Finish signing in from your browser, with Cancel sign-in; the flow stops after five minutes. It then moves through Finishing sign-in to Signed in to host, which dismisses itself. If it fails, it says Sign-in timed out, Sign-in failed or Couldn't start sign-in (the preview wasn't ready yet) and offers Retry.