Troubleshooting

Start with doctor --path <theme> to inspect plugin-owned state. For machine processing, use --json and branch on stable diagnostic codes such as target.structure, mixer.index, layout.render, and lock.active rather than terminal prose. Diagnostics do not acquire or repair the target lock, modify Git, or connect to a store.

Theme Target does not resolve

Run the command from the Vite project root and confirm that --path identifies the real theme root, which must contain layout/ and snippets/. A direct Vite run needs themePath in the plugin options; it does not inherit Theme Run's private context. When both are present, themePath must point to the same target as --path.

The dev branch check fails

With the default devBranches: ["dev"], dev only starts when the Theme Target's current branch name starts with dev. A detached HEAD or a directory without Git also fails this check. Switch branches, adjust devBranches, or set it to false.

The target is already in use

Operations on the same real Theme Target are mutually exclusive; separate targets can run in parallel. Confirm whether the recorded process is still alive. The plugin can recover a lock whose owner has exited. If the recovery guard itself was abandoned, the operation fails closed and reports the location that requires manual attention; act on that exact diagnostic instead of deleting locks for other targets.

A warning that lists existing shopify theme dev or shopify app dev processes comes from maxDevProcesses. It does not block startup, but several dev processes share the same account's API limits and can slow previews.

The Mixer blocks development

Check that the Mixer is tracked, the Git index contains the current production form, and its marker matches the installed plugin. Run a production build again, inspect the change, and stage the generated files. Do not bypass the check or copy a development origin by hand.

Production verification fails

The build, push, and package gate checks that the Mixer is in production form, that layout/theme.liquid renders it, and that the standard theme directories contain no /@vite/client reference. It also rejects unresolved build-time alias imports such as #theme/ in assets/*.js, and references to cdn.jsdelivr.net, unpkg.com, or cdnjs.cloudflare.com. Fix the actual build or layout state and rerun the complete command rather than bypassing the gate before a push or package.

A phone opens the preview but assets fail

Check Shopify preview reachability and Vite-origin reachability separately, then check whether an HTTPS page is attempting to load LAN HTTP assets. Repeat the steps in phone and LAN debugging.