Troubleshoot preview and publishing

Match storefront, build, publication, checkout, and domain states to the safest next action.

Entry path: Workspace → select a store → Storefront → reproduce the preview or publication state shown on screen

What this covers

Identify which layer is failing—project version, preview, build check, publication, public catalog, checkout, or domain—and take the smallest safe recovery action.

The storefront journey has several independent layers. Repeating Publish cannot fix missing product data, and refreshing Preview cannot repair a payment connection. Start with the exact message and surface that failed.

Availability and prerequisites

Keep the project open and note the current version label.
Record the exact message, page path, and whether it appeared in Preview or on the public URL.
Wait for active Runner work to reach Completed, Failed, or Stopped before starting a conflicting recovery action.
Do not remove domains, restore versions, or repeat paid actions just to test a theory.

Find the failing layer

In Storefront, check whether a current version exists.
Confirm whether normal Preview opens.
If you are publishing, read the result of the build check before selecting another action.
If publication succeeds, open the public URL rather than the preview URL.
On the public store, test the catalog and cart.
Check Runner's checkout status and the actual checkout path.
If only the custom address fails, check Domain Settings last.

Important recovery controls

Control	What happens when selected
Refresh in Preview	Reloads the current preview and clears the active Design Mode selection and undo/redo session. Save pending direct edits first.
Fix / Fix error	Sends the displayed preview diagnostic to Runner as a repair request. Dismiss only hides the message.
Fix with AI	Closes the publication confirmation and sends its build failure to Runner for repair; publication does not start.
Retry check	Runs the storefront build check again after Runner could not reach the workspace.
Open Store Operations	Closes the publication confirmation and opens Store Operations so you can complete the named setup.
Retry setup status	Checks Store Operations readiness again after its status was unavailable.
Republish	Starts a fresh checked publication attempt after a failed or linkless result. Fix the named cause first.
Retry checkout status	Checks again for an enabled payment connection; it does not test a product, shipping, or the checkout form.

State-to-action reference

Message or symptom	Layer	What it means	Safest next action
No storefront yet	Project version	No previewable version exists.	Ask Runner to build the first storefront.
Building the first version…	Project version	Runner is still creating it.	Follow task progress; do not publish yet.
Build failed on a version	Project version	That version is not ready.	Open the task details and ask Runner to repair the failure.
Preparing preview…	Preview	Runner is starting the selected preview.	Keep the latest version selected; refresh only if progress stops.
Failed to load the preview for this version	Preview	The selected version could not be displayed.	Return to current, refresh, or try another ready version.
Reconnecting preview	Preview	Runner lost the preview connection and is retrying.	Follow the retry count; reconnect the workspace if recovery fails.
Preview error bar with Fix	Preview	The running page reported a diagnostic Runner can use.	Select Show more to inspect it, Fix or Fix error to send it to Runner, or Dismiss only to hide the bar.
Page not found	Preview or public route	The path does not exist in that version.	Return to `/`, use visible navigation, and ask Runner to create or repair the route.
Design mode didn't start	Design Mode	The editable preview did not become ready.	Select Try Again, or return to current Preview and refresh.
Visual editor disabled while AI is processing	Design Mode	Runner is handling another request.	Wait for Runner to finish.
Failed to load version history	Version history	The version list request failed.	Select Try Again.
Restore is blocked	Version history	Runner is active or the version is not ready.	Wait for Runner, then choose a ready version.
We couldn't reach your workspace	Publication check	Runner could not run the build check.	Select Retry check; reconnect the workspace if it repeats.
Something went wrong while building your store	Publication check	Current storefront cannot pass the build.	Select Fix with AI, review the repair, then rerun the checks.
Store setup is incomplete	Publication setup	Important store operations remain unfinished.	Select Open Store Operations. Acknowledge only if the limitation is intentional.
We couldn't verify Store Operations	Publication setup	Setup status is unknown.	Select Retry setup status before considering an acknowledgment.
No code changes detected	Publication changes	Runner found nothing new since the last publication.	Cancel, or acknowledge a same-state redeploy only when intentional.
Payment integration is not configured	Checkout setup	Some publication flows show this before launch when no enabled payment connection is found.	Connect Stripe; use the acknowledgment only for an intentional browse-only launch. Other flows report checkout status after publication.
Store publish failed	Publication	The attempt did not complete.	Repair the named issue, then select Republish.
Store link unavailable	Publication handoff	The attempt finished without a usable public URL in Runner.	Close the dialog, confirm the workspace is ready, then select Republish.
Public store shows old content	Publication or version	The current project changes are not live.	Confirm the latest current version, select Publish Changes, and reopen the public URL.
Product missing on public store	Catalog	Publication succeeded, but the intended product is not visible.	Check product status, market, price, and inventory; publish changes if required.
Cart action missing or disabled	Catalog or availability	The selected item cannot currently be added.	Check required options, availability, stock, price, and region.
Checkout paused	Payment	The post-publish flow did not find an enabled Stripe connection.	Select Connect Stripe, then retest the actual checkout path.
Checkout status unavailable	Payment status	Runner cannot confirm payment readiness.	Select Retry checkout status and test the public checkout independently.
Custom domain says Misconfigured	Domain	Expected DNS records are not verified.	Copy the displayed DNS values exactly to your provider, then recheck.
Transfer in progress	Domain	A domain is moving between stores.	Do not start another transfer; follow the shown status.

Report a problem to Runner

Include these details in one message:

the exact page path or public URL;
whether it failed in Preview or on the live store;
the current version label;
the exact error or state text;
the last button you selected;
the expected result; and
whether the issue reproduces after the documented retry action.

For a visual problem, include the device layout and a screenshot. For checkout, stop before a real charge and report the last successful step.

Recovery boundaries

Do not repeatedly resume or republish an unchanged failed state. Fix the named cause first.
Do not restore an older version while Runner is working.
Do not remove a domain to fix a storefront or checkout issue.
Do not claim launch success until the public URL, intended catalog, cart, and required checkout step have each been checked.