> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve ThemeDocument validation, preview, revision, and build problems on either lane.

## A setting is rejected

Fetch the current document schema, then compare it against the field name and
value type you sent. Shoppex rejects unknown keys and unsupported block types
on purpose, instead of guessing what you meant.

## The preview shows an older change

Reload the draft, then confirm you edited the theme and page you expected. If
another editor published a newer revision, load it, apply your change to it
again, and preview it.

## Publishing reports a revision conflict

Someone else saved or published just before you did.
Fetch the latest draft, reapply your change, preview it, then publish again.

## The live storefront is unavailable

Confirm that the theme has a valid published document and that it is active.
If the dashboard state looks correct, contact Shoppex Support. Give them the
shop domain, the theme ID, the rough time it happened, and the request ID if
one is shown.

## An Advanced storefront fails to build

`deploy` and `status` print the failure kind, the reason recorded by the
build, what to do about it, and the tail of the build log.

* `lockfile_out_of_sync` is the most common failure. Your `package.json` and
  your lockfile disagree, because a dependency changed without a matching
  `bun install`. Run `bun install`, then push again so the updated lockfile
  ships with your source.
* `workspace_unavailable` is a Shoppex-side failure, not a problem with your
  source. Retry the build.

See [Theme CLI](/storefront/theme-cli) for the full `deploy` and `status`
behavior.

## An import or replace is rejected

Every import and replace enforces the same limits: a 42 MiB ZIP, a 40 MiB
extracted source tree, 400 files, a 5 MiB single file, and 512-character
paths. A symbolic link, an absolute path, a path containing `..`, or two
paths that collide only by letter case also fail the upload. A missing root
`package.json`, or one without a `build` script, fails too. See
[Code storefronts](/storefront/code-storefronts) for the complete list of
requirements.

## A CLI push or replace reports a revision conflict

Someone else saved a newer revision while you worked: another developer, an
AI edit, or a different CLI push. Pull the latest source, then push or
replace again. A pull also applies any remote deletions to your local copy.