---
title: Troubleshoot storefront builds
description: Diagnose a blank, stale, broken, or visually incorrect storefront preview before publishing it.
---

The preview is the safest place to find storefront problems. Do not publish until the important pages and interactions work there.

**Entry path:** Runner documentation → **Help and reference** → **Troubleshoot storefront builds**.

## Before you start

- Open the affected store and identify the page and device width where the problem appears.
- Let the latest Runner task finish before comparing its result with Preview.
- Use Preview first; do not publish a broken or uncertain result as a test.

## Start in Storefront

1. Open the affected store and select **Storefront**.
2. Confirm the preview is showing the expected project and latest version.
3. Reload the preview once.
4. Check desktop and mobile device views.
5. Open the affected page through the preview navigation.
6. Compare the result with the latest Runner task and version history.

## Common problems

| What you see | What to check |
| --- | --- |
| Blank or error preview | Wait for the active build to finish, reload once, and inspect the current task for a failure. |
| Old content | Confirm the latest task completed and that the preview is on the newest version. |
| Layout breaks at one width | Reproduce it with the device controls and tell Runner the page, section, and width. |
| Missing image | Check Media Library, the asset selection, and whether the image itself loads. |
| Link opens the wrong page | Name the source button and intended destination in a focused correction. |
| Product is missing | Verify that the product exists and is available to the storefront, not just that the page looks polished. |
| Design Mode change is absent | Confirm the edit was saved or applied, then reopen the same page in preview. |

## Useful controls

| Control | Result |
| --- | --- |
| Refresh preview | Reloads the current preview without publishing it. |
| Device selector | Changes the preview width so you can inspect responsive layouts. |
| Open preview or external view | Opens a larger preview; it does not make the store live. |
| Design Mode | Lets you select and adjust visible storefront content. |
| Version History | Shows saved versions and restore controls. Restoring changes project state, so review first. |

## Escalate with useful evidence

Include the project name, page, device size, expected result, visible result, latest task state, and a screenshot without personal or customer data.

## Related guides

- [Preview your store](../storefront-and-publishing/preview-your-store)
- [Design Mode](../storefront-and-publishing/design-mode)
- [Version history](../storefront-and-publishing/version-history)
- [Troubleshoot Runner tasks](./troubleshoot-runner-tasks)