Skip to content

fix: A preview whose app never started is hot-restarted, not shown blank - #2

Merged
vlidholt merged 1 commit into
mainfrom
fix/preview-stall-hot-restart
Nov 15, 2026
Merged

vlidholt merged 1 commit into
mainfrom
fix/preview-stall-hot-restart

Conversation

@vlidholt

Copy link
Copy Markdown
Contributor

Problem

Sometimes, after creating a project, the preview ends up on a white screen with the app never loaded. Pressing Hot Restart fixes it.

PreviewPane waits 8 s for the app's main() to run (_waitForFlutterMain). When that ran out it called markPreviewLive() anyway, which:

  • dropped the loading overlay onto a blank page,
  • set the phase to ready,
  • raised "Your project has started" over it.

Nothing ever retried.

Fix

  • Hot Restart fallback. When main() hasn't run in time, the first load calls the new ServerpodProcessController.recoverStalledPreview() instead of revealing the page. So does the hard reload a project switch does. It is the runner's hot restart, the same as the button, and that restart's hard reload reveals the page. Full Restart is not used: it costs minutes.
    • It fires at most once per load. A reload that a hot restart asked for never recovers, so a page that never starts cannot loop.
    • When no restart is possible (server not running, another action running, or the runner refuses), the page is revealed as before.
    • Each time it fires, App Studio's log records "The app did not start in the preview. Hot restarting it."
  • No more dropped changes. Process changes that landed while the webview was initializing (a new URL, a stop, a reload request) used to be ignored until the runner next notified. _ensureWebView now catches up on them once init succeeds. It doesn't after a failed init, which would otherwise retry at once, forever.

Root cause: not found

Ruled out by testing against a scratch Flutter web app:

  • A second main() call (the bootstrap fallback racing DWDS's RunRequest): the engine throws "Invalid engine initialization state" and the app renders normally.
  • A hard reload during the first load (the project-switch path): DWDS still runs main() about 0.5 s later, with the fallback switched off.
  • The New Project route clearing the navigator twice: a popping route isn't "present", so popUntil stops at home.

A freshly created Serverpod template app reaches main() about 2.3 s after navigation on an idle Mac.

Testing

  • flutter analyze is clean and the full flutter test suite passes.
  • Four new tests in test/process/serverpod_process_test.dart cover recoverStalledPreview: it restarts and reloads, leaves a refused restart to the pane, does nothing once live, and does nothing before the server is running.
  • The pane side needs a real CEF browser, so it has no automated test. The fallback has not been seen firing in the running app.

🤖 Generated with Claude Code

…ank.

The pane waits 8 s for the app's main() and used to mark the preview live
regardless, which dropped the overlay onto a white page, reported it as
running and raised "Your project has started" over it. Seen after creating
a project; pressing Hot Restart cured it. The first load (and the reload a
project switch does) now falls back to the runner's hot restart, whose hard
reload reveals the page. Once per load, and revealed as before when no
restart is possible.

Process changes that landed while the webview was initializing were also
dropped until the runner next notified; the pane now catches up on them
once init finishes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vlidholt
vlidholt merged commit 7d59f7d into main Nov 15, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant