# Why is my preview blank?

> A blank preview is a runtime error nine times out of ten. The sentence that gets it diagnosed in one turn, and what to reset when it is genuinely wedged.

Canonical: https://vibely.sh/guides/why-is-my-preview-blank
Last updated: 2026-09-19

Published 2026-09-19 · Troubleshooting · 6 min read

## Reference documentation

- [Debugging](https://docs.vibely.sh/prompting/debugging)
- [Preview](https://docs.vibely.sh/features/projects/preview)
- [Testing](https://docs.vibely.sh/features/testing/overview)

The preview is your project's dev server running in an iframe. A blank white screen almost always means the app threw before it rendered anything — a bad import, an undefined read during the first paint, a provider missing above a hook. The console knows; you just have to ask for it.

## Type this first

> "The preview is blank. Read the runtime errors and tell me what's throwing."

On a broken preview the agent's first move is to read the console the preview has *already captured* — no browser round trip, no waiting. It only opens a browser when that log does not explain the failure, or when you ask it to.

That second half matters more than it looks. **Verification is on-demand.** The agent does not self-review its work and does not drive a browser unless your prompt says so. If you want proof rather than a claim, ask for it in words: *"Test the login flow in the browser and tell me what you saw."*

## What is already checked on every turn

| Runs every turn, no prompt needed | Only when you ask |
| --- | --- |
| TypeScript type-check of the project | Clicking through a flow in a browser |
| Web: every route loaded in a headless browser to catch runtime errors | A screenshot to judge how something looks |
| Mobile: the Metro bundle gate | Checking a form actually submits |
| Failures handed back to the agent to fix before the turn ends | Checking a fix on a real device |

So "I've fixed it" means the code type-checks and the routes load. That is a real gate, and it is not the same claim as "the button works".

## Describe it in four lines

If the first answer misses, the fastest correction is a better report: **steps**, **expected**, **what actually happens**, and **where** — preview or published, web preview or a real device, which browser. That last line often names the cause by itself. "Started after the turn where we added validation" narrows the search to one diff.

Paste errors verbatim — the full message and stack. A retyped error loses the file, the line and the exact identifier, which is most of the information.

## When it is not an error but a stale view

- **Reload** in the preview bar remounts the iframe and re-probes the dev server. Use it when hot reload has clearly stopped landing.
- **Restart** in the project menu rebuilds the sandbox from your current files. The preview URL does not change.
- Edits normally land over hot reload in about a second, and the platform reloads for new files, config changes and dependency installs. If you routinely need a restart to see an edit, that is a bug worth reporting, not a workflow.
- **On a phone**, a stale build is usually [Expo Go](https://vibely.sh/glossary/expo-go) holding an old bundle: shake the device, Reload, and re-scan the QR code if it does not come back.

## Nearby symptoms, and the prompt that fits

| Symptom | Type this |
| --- | --- |
| A button does nothing | "This control is a no-op. Find every handler in this screen that isn't wired and fix them." |
| Works in preview, broken once published | "It works in the preview and fails on the published URL. What differs between the two?" |
| Works in the web preview, broken on device | "It works in the web preview but fails in Expo Go on my phone. That means it's native — investigate." |
| A query returns nothing but rows exist | "Check the RLS policies and the grants on that table." |
| You do not believe the fix | "Test it in the browser and tell me exactly what you saw, step by step." |

## If it keeps making the same wrong edit

Stop building and switch to [plan mode](https://vibely.sh/guides/how-to-use-plan-mode). More build turns on a wrong mental model just reinforce it; a read-only diagnosis turn breaks the loop.

## Related

- [How to sync your project to GitHub](https://vibely.sh/guides/how-to-sync-your-project-to-github) - previous guide
- [How credits are charged](https://vibely.sh/guides/how-credits-are-charged) - next guide
- [Troubleshooting guides](https://vibely.sh/guides/category/troubleshooting)
