---
title: "Troubleshoot previews"
description: "Symptom-by-symptom fixes for previews that won't start: build failures, database errors, and port issues."
url: https://evonx.ai/docs/preview-and-debug/troubleshoot-previews
locale: en
updated: 2026-09-04
---

# Troubleshoot previews

Symptom-by-symptom fixes for previews that won't start: build failures, database errors, and port issues.

Find your symptom, apply the fix. When none of these match, the catch-all is
[Analyse & Fix](/docs/preview-and-debug/analyse-and-fix) — it reads the logs so
you don't have to.

## The preview won't start

**The build fails.** The [logs](/docs/preview-and-debug/reading-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](/docs/preview-and-debug/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](/docs/preview-and-debug/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](/docs/preview-and-debug/annotate-preview). See
[Test on your phone](/docs/preview-and-debug/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](/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](/docs/preview-and-debug/analyse-and-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](/docs/preview-and-debug/preview-databases).

> **Tip**
> The reflex worth building: **reproduce with the logs open**. Almost every preview
> mystery prints its explanation the moment it happens.

## Related

- [Analyse & Fix](/docs/preview-and-debug/analyse-and-fix) — the automated path
  when the logs are a wall of text.
- [Reading preview logs](/docs/preview-and-debug/reading-logs) — how to find the
  first error yourself.