Troubleshoot previews

Find your symptom, apply the fix. When none of these match, the catch-all is Analyse & Fix — it reads the logs so you don't have to.

The preview won't start

The build fails. The logs end in a build or compile error. This is a code problem from a recent change — run Analyse & Fix, or reply in the responsible thread.

It hangs on install or build. First boots are legitimately slow — dependencies install from scratch. If there's been no new log output for several minutes, stop the preview and start it again; a stale cache or transient network failure usually doesn't survive a restart.

A database error during startup (API previews). Migrations and schema disagree — typical right after a change that edits the data model. Analyse & Fix resolves the mismatch; see Preview databases for how the ephemeral database is prepared.

The preview was working, now it's gone

The link is dead / the preview vanished. Previews are ephemeral: idle ones are cleaned up automatically to free resources. Nothing is lost — your code is in the repository — so just start a fresh preview. Remember the database resets with it.

It shows old behavior. You're likely previewing a different branch or thread workspace than you think. Check which source the preview was started from in the Preview Hub; a thread's changes appear in its preview, not in one built from your default branch.

It starts, but misbehaves

Blank page or spinner forever. Open the logs and watch while you reload the page — a runtime error will print at that moment. Hand it to Analyse & Fix.

Wrong or missing data. Previews run on seed data, not your production records. An empty screen may just mean the seeds don't cover that case — ask the AI to extend them.

Works on desktop, broken on your phone. Genuine layout bugs; report them with screenshots or annotations. See Test on your phone.

A new preview won't start at all

You may be at your workspace's limit for concurrently running previews. Stop one you're done with in the Preview Hub and start the new one. Limits follow your plan — see pricing.

The API preview cannot reach the database

Logs mention localhost:5432, connection refused, or "database does not exist". The API is still aiming at a machine-local Postgres instead of the preview database Evonx started. Restart the preview so environment injection runs again. If it keeps happening after a code change, use Analyse & Fix — that is the usual path when the app ignores the injected connection string.

The app boots, then crashes on a missing table (for example a seed step talking about a relation that does not exist). Migrations and the model have drifted. Analyse & Fix, or ask a thread to make the schema match what startup expects. See Preview databases.

Related

• Analyse & Fix — the automated path when the logs are a wall of text.
• Reading preview logs — how to find the first error yourself.