Both errors that stop shopify app dev cold on a theme app extension have documented, reproducible causes. The uid identifiers error means the CLI cannot map your local extension to its record on Shopify's platform, while Unexpected end of JSON input usually traces back to a corrupted or empty local config file. Fix the uid problem with an interactive deploy; fix the JSON error by writing a valid object into the broken config file.
Key takeaways
- The
uidfield inshopify.extension.tomlis app-scoped and required by every extension; it is generated automatically when you scaffold with Shopify CLI but must be committed to source control. - Running
shopify app deploywithout--forceis the prescribed one-time step to stamp UIDs onto legacy extensions that pre-date the Dev Dashboard migration. Unexpected end of JSON inputduringshopify app devis almost always caused by an empty or missingshopify-cli-theme-conf-nodejsconfig file, not by your Liquid or TOML.- Deleting the
.shopifyfolder and re-runningshopify app devresolves a stale session state that blocks uid assignment in dev mode even after a successful deploy. - Always commit updated
.tomlfiles to source control immediately after the uid-stamping deploy, or the CLI will try to delete and recreate extensions on the next run.
What the uid field actually is
The uid field is a required, app-scoped identifier that shopify app deploy uses to determine whether an extension is being created, updated, or deleted. It is created and managed by Shopify: generated automatically when you scaffold the extension with Shopify CLI, so you do not need to set or edit it manually.
That last sentence is the trap. It is generated automatically on scaffold, but only written back to your .toml during an interactive deploy. If you built the extension before Shopify introduced the Dev Dashboard migration, your shopify.extension.toml has no uid line, and the CLI now refuses to continue in dev mode until one exists.
The user identifiers appear in the shopify.extension.toml as a new uid property on each extension, and by default the UID is deterministically set based on the extension handle, so it will always be the same for extensions with the same handle value.
A uid looks like this:
name = "my-theme-extension"
type = "theme"
uid = "fddfc370-27c7-c30f-4ee0-a927194e2accadefd40c"
It is not the same as the old EXTENSION_UUID from the .env file used in CLI 2. That UUID was used to identify the extension record in the Partner Dashboard. The uid is a newer, TOML-resident identifier that the next-gen Dev Dashboard uses to track add, update, and delete operations across versions.
Error 1: "Your app has extensions which need to be assigned uid identifiers"
When it appears
The error reads: Your app has extensions which need to be assigned uid identifiers. It surfaces when you run shopify app dev and the CLI finds at least one shopify.extension.toml with no uid field.
This hits teams in two common situations:
- Legacy apps migrated to the Dev Dashboard. Apps built on CLI 2 (Partners Dashboard managed) that are migrating to the Next-gen Dev Dashboard have extensions with no
uidin their TOML files. - CI/CD pipelines that used
--force. If you runshopify app deploy --forcefrom a container, the UID values that deploy would have added to your extension TOMLs never get committed. Shopify recommends logging into the Developer Dashboard, grabbing the UID values from your app version info, and adding them to your extension TOML files, or you risk future changes causing a delete and re-add of your extensions.
The fix
Step 1. Update the CLI to the latest version. The uid migration path is only reliable on current tooling.
npm install -g @shopify/cli@latest
# or via homebrew:
brew upgrade shopify-cli
Step 2. Run an interactive deploy without --force:
shopify app deploy
Once updated, you just need to run a single interactive shopify app deploy from your project directory. This special deployment will automatically generate new permanent IDs (uids) for your extensions and save them to your shopify.extension.toml configuration files, and the CLI will prompt you to confirm these changes. After the deployment succeeds, it is crucial that you commit these updated .toml files to your source control.
Step 3. If the deploy says No extensions to migrate after running shopify app import-extensions, that is expected. Migrating dashboard-managed extensions is part of the process, but any apps with extensions also need to run an app deploy to assign new uid identifiers. import-extensions and deploy are separate steps.
Step 4. If shopify app dev still fails after a confirmed deploy, delete the stale session cache:
rm -rf .shopify
shopify app dev
All you need to do is delete the .shopify folder and run shopify app dev in the console and go through the steps to set up the project (choose store, etc.).
Legacy UUID preservation for theme app extensions
If you are migrating a theme app extension that is already installed on merchant stores, the uid must map to the existing extension UUID. Swapping in a fresh UID created by a clean scaffold will register a new extension, orphaning every merchant install.
Confirm that the shopify.app.toml file has the include_config_on_deploy property set to true to ensure the new configurations are included on all app deploys. Additionally confirm that the extension UUIDs have been mapped correctly, with the UUID listed in the shopify.extension.toml file, following the migration guide for migrating to extension user identifiers.
If you lost the original UUID from your old .env file, navigate to Partners Dashboard > App > Extensions and copy the UUID from the extension's URL.
Error 2: "Unexpected end of JSON input"
This one is disorienting because the message looks like a network or API problem. It is not.
Root cause
Running shopify app dev crashes with Unexpected end of JSON input after scaffolding a theme app extension with no other modifications. The config file within ~/Library/Preferences/shopify-cli-theme-conf-nodejs was empty, causing that error.
The CLI reads this file at startup to restore preferences for the theme dev server (things like the preview password and the last-used store). If the file exists but is empty, JSON.parse throws SyntaxError: Unexpected end of JSON input before the app process fully boots. The error bubbles up with no line number, so it looks fatal.
Verifying the cause
# macOS
cat ~/Library/Preferences/shopify-cli-theme-conf-nodejs
# If the output is blank, that is your problem.
On Linux, the same file typically lives at ~/.config/shopify/shopify-cli-theme-conf-nodejs or under the XDG config home.
The fix
Add an empty object to the file and save it. Run shopify app dev from your original app directory; this time you will be asked for the dev store's preview password, and it will then store a valid value into the config file and run the app with no further issues. This was likely a config hiccup from a corrupted empty config file in the local dev environment.
echo '{}' > ~/Library/Preferences/shopify-cli-theme-conf-nodejs
shopify app dev
After entering the store preview password, the file is rewritten with valid JSON and the error disappears permanently.
Error comparison table
| Error | Root cause | First check | Fix |
|---|---|---|---|
uid identifiers during shopify app dev | Extension TOML missing uid field | Does shopify.extension.toml contain a uid = line? | Run shopify app deploy interactively, then commit TOMLs |
uid identifiers after deploy succeeds | Stale .shopify session cache | Does .shopify/ exist in the project root? | Delete .shopify/ and re-run shopify app dev |
Unexpected end of JSON input | Empty shopify-cli-theme-conf-nodejs file | Run cat on the file; blank output confirms it | Write {} to the file, then re-run shopify app dev |
| Extension not visible in Theme Editor after uid migration | include_config_on_deploy not set to true | Check shopify.app.toml for the property | Set include_config_on_deploy = true and redeploy |
| App embed broken after CLI upgrade (uid auto-added) | UID in TOML does not match the deployed extension record | Compare TOML uid against Partner Dashboard extension ID | Map original UUID from Dashboard, update TOML, redeploy |
Directory structure that avoids both errors
Here is the layout the CLI expects for a Remix app with a theme app extension. Any deviation, particularly a missing shopify.extension.toml or a TOML in the wrong directory, causes the CLI to skip the extension entirely or crash.
my-app/
├── shopify.app.toml # include_config_on_deploy = true
├── package.json
└── extensions/
└── my-theme-extension/
├── shopify.extension.toml # uid = "..."
├── blocks/
│ └── my-block.liquid
├── snippets/
└── assets/
Key structural rules:
- Each extension lives in its own subdirectory under
extensions/. shopify.extension.tomlmust be at the root of that subdirectory, not nested insideblocks/or anywhere else.- The
uidfield must be present and must match the value stored on Shopify's platform for existing extensions. - For theme app extensions specifically, the
typemust be"theme", not"theme_app_extension"(the old CLI 2 value).
CI/CD-safe uid workflow
If your pipeline uses --force, you will never be interactively prompted to confirm UID stamping, and your TOML files on disk will silently stay uid-free. Here is how I handle this across the app projects I maintain:
- Run the uid-stamping deploy once from a local machine, interactively, without
--force. - Commit the updated TOML files to source control immediately. The CI pipeline picks them up on the next run.
- Pipeline continues using
--forcenormally. The UIDs are now baked into the committed TOMLs, so no interactive prompt is needed. - Never let the pipeline generate a fresh scaffold. If a team member runs
shopify app generate extensionfor a new extension, the resulting TOML will have an auto-generated UID that has never been deployed. That is fine, but it needs a local interactive deploy before the CI pipeline can use--forcesafely.
For a deeper look at how the CLI maps extension identifiers to their platform records, see my glossary entry on extension UIDs.
Conclusion
Both errors feel opaque when you first hit them, but they have narrow, well-defined causes. The uid error is a migration artifact from Shopify's move to the next-gen Dev Dashboard, and the JSON error is a corrupted local preferences file. Neither requires changes to your Liquid, your app logic, or your TOML structure beyond adding the uid field. Run the interactive deploy, commit the resulting TOML files, write {} into the broken config file if needed, and both issues are closed.
If you need this built rather than doing it in house, Lintel, the studio I run, takes on custom Shopify app development projects like this.
Frequently asked questions
What is the uid field in shopify.extension.toml and where does it come from?
The uid is a required, app-scoped identifier written into each extension's shopify.extension.toml file. It is generated automatically when you scaffold a new extension with Shopify CLI, or stamped onto existing extensions during an interactive shopify app deploy as part of the Dev Dashboard migration. You should never edit it manually.
Why does shopify app deploy succeed but shopify app dev still show the uid error?
A successful deploy writes the uid to your TOML files on disk, but the .shopify folder in your project root caches session state from before the uid existed. Delete the .shopify folder and run shopify app dev again to pick up the updated TOML values and start a fresh session.
Can I reuse the same uid across multiple apps or stores?
No. The uid is app-scoped, meaning it must be unique within a single app and ties your local extension directory to one specific extension record on Shopify's platform. Copying a uid from another app or another extension will cause the CLI to overwrite or conflict with the wrong extension record on deploy.