November 5, 2026 · 8 min read

Fixing Shopify CLI Theme App Extension Errors: uid Identifiers and Unexpected end of JSON input

Two Shopify CLI errors block theme app extension dev sessions: missing uid identifiers and Unexpected end of JSON input.

Fixing Shopify CLI Theme App Extension Errors: uid Identifiers and Unexpected end of JSON input

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 uid field in shopify.extension.toml is 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 deploy without --force is the prescribed one-time step to stamp UIDs onto legacy extensions that pre-date the Dev Dashboard migration.
  • Unexpected end of JSON input during shopify app dev is almost always caused by an empty or missing shopify-cli-theme-conf-nodejs config file, not by your Liquid or TOML.
  • Deleting the .shopify folder and re-running shopify app dev resolves a stale session state that blocks uid assignment in dev mode even after a successful deploy.
  • Always commit updated .toml files 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 uid in their TOML files.
  • CI/CD pipelines that used --force. If you run shopify app deploy --force from 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

ErrorRoot causeFirst checkFix
uid identifiers during shopify app devExtension TOML missing uid fieldDoes shopify.extension.toml contain a uid = line?Run shopify app deploy interactively, then commit TOMLs
uid identifiers after deploy succeedsStale .shopify session cacheDoes .shopify/ exist in the project root?Delete .shopify/ and re-run shopify app dev
Unexpected end of JSON inputEmpty shopify-cli-theme-conf-nodejs fileRun cat on the file; blank output confirms itWrite {} to the file, then re-run shopify app dev
Extension not visible in Theme Editor after uid migrationinclude_config_on_deploy not set to trueCheck shopify.app.toml for the propertySet 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 recordCompare TOML uid against Partner Dashboard extension IDMap 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.toml must be at the root of that subdirectory, not nested inside blocks/ or anywhere else.
  • The uid field must be present and must match the value stored on Shopify's platform for existing extensions.
  • For theme app extensions specifically, the type must 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:

  1. Run the uid-stamping deploy once from a local machine, interactively, without --force.
  2. Commit the updated TOML files to source control immediately. The CI pipeline picks them up on the next run.
  3. Pipeline continues using --force normally. The UIDs are now baked into the committed TOMLs, so no interactive prompt is needed.
  4. Never let the pipeline generate a fresh scaffold. If a team member runs shopify app generate extension for 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 --force safely.

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.

shopify clitheme app extensionshopify app devdebuggingextensions

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.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn