Getting error: Validation errors in shopify.app.toml:

Shopify CLI and Libraries
,
1

I have reproduced the issue on the latest CLI version.

Yes, I am on the latest version

I have searched existing posts and this report is not a duplicate.

Yes, this isn’t a duplicate

In which of these areas are you experiencing a problem?

App

Expected behavior

It should have run the app locally

Actual behavior

It gave an error:
App configuration is not valid
Validation errors in shopify.app.toml:
• [definitions]: Required

Reproduction steps

npm run dev

Verbose output

npm verbose cli C:\Program Files\nodejs\node.exe C:\Program Files\nodejs\node_modules\npm\bin\npm-cli.js
npm info using npm@10.9.2
npm info using node@v22.17.0
npm verbose title npm run dev
npm verbose argv “run” “dev” “–loglevel” “verbose”
npm verbose logfile logs-max:10 dir:C:\Users\Msi\AppData\Local\npm-cache_logs\2026-06-20T10_33_36_066Z-
npm verbose logfile C:\Users\Msi\AppData\Local\npm-cache_logs\2026-06-20T10_33_36_066Z-debug-0.log

dev
shopify app dev --config=shopify.app.toml

╭─ error ──────────────────────────────────────────────────────────────────────╮
│ │
│ App configuration is not valid │
│ Validation errors in shopify.app.toml: │
│ │
│ • [definitions]: Required │
│ │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯

npm verbose cwd
npm verbose os Windows_NT 10.0.26200
npm verbose node v22.17.0
npm verbose npm v10.9.2
npm verbose exit 1
npm verbose code 1

Operating system

Windows 11

CLI version

3.88.0

2

I’m seeing the exact same issue across all of my apps.

I spent a few hours debugging it and found some interesting things:

  • The error reproduces in a completely fresh directory with only npm init -y and a standard shopify.app.toml, so it doesn’t appear to be project-specific.

  • It reproduces across multiple existing apps that were working fine yesterday.

  • It reproduces on both Shopify CLI 3.84.x and 3.92.x.

  • Shopify CLI verbose logs consistently show:

The following extension specifications were defined locally but not found in the remote specifications: tax_calculation

even though there are no extensions or functions in the project.

I also experimented with the missing definitions field. Adding:

definitions = [
  { handle = "test", display_name = "Test" }
]

gets past the validation error, but then deployment fails because Shopify interprets it as an order_attribution_config and asks for a sales channel/channel config extension.

That makes me think the CLI is validating against an unexpected schema or capability rather than there actually being a problem with the app TOML itself.

Curious if anyone else seeing this can check whether their verbose logs also contain the tax_calculation specification message.

3

Another reason why I do not use TOML file or Shopify CLI for anything outside the bare minimum and continue to do metafield creation, scopes auth, webhooks and more with the API.

For one you cannot have stability when you have to upgrade all the time

4

Also seeing the same issue. I’m convinced this is a validation issue on Shopify’s side. Our TOML has not changed and dev was working fine yesterday.

5

I have the same issue does any one found a solutions?

8

Same error, different setup — wanted to add data points in case it helps narrow the trigger.

My setup:

  • @shopify/cli@3.90.1 (pinned ~3.90.0 after upgrading from ^3.91.1 hoping to dodge the issue — same error on both)
  • @shopify/shopify_function@2.0.1 (in extensions/cart-transformer/)
  • @shopify/shopify_function@1.0.6 (in the app-extension root — hoisted)
  • Node 22.x, macOS
  • App type: embedded Public app for product options/add-ons. Not a sales channel.

Extensions in the app:

  • theme-extension (theme app block)
  • cart-transformer — type function, target cart.transform.run, export cart-transform-run

Scopes:
scopes = “read_themes,write_cart_transforms,write_files,write_products”

What I tried (per Nitin_Jangra’s workaround):

Adding the minimal [[definitions]] block satisfies the validator:
[[definitions]]
handle = “xxxxxxx”
display_name = “xxxxxxx”

…but immediately on npm run dev it errors with:
:cross_mark: Error
└ To write order attribution definitions, configure your app to create channels by adding a
channel config extension. Learn more:

9

I had the same issue, but I had a quite old shopify cli version.

I upgraded to 3.94.3, not the latest (because we still haven’t updated our project to node22) and it stopped happening.

Maybe something in the shopify cli 3.94.3 version prevents the error from happening, or it might be something completely different.

10

Same issue here.
CLI version 3.92.1
Was working 1-2 days ago, error today.

11

I face the same issue
App configuration is not valid Validation errors in shopify.app.myapp.toml: [definitions]: Required
2 days ago it worked well, but now can’t run “Shopify app dev”. How to fix it?

12

Looks like this is duplicated issue of Shopify cli error.

I had the same error, and updating the CLI to 4.2.0 resolved it for me.

13

If anyone is still encountering this issue after updating to CLI version 4.2.0, please let us know.

14

Its fixed in 4.2.0. Thanks for the prompt resolution.

15

@Paige-Shopify Will this issue be fixed for earlier versions, or do we need to be upgraded to version 4.2.0?

16

Can you try updating your CLI to lastest one using npm install -g @shopify/cli@latest ( i.e shopify version 4.2.0 ) as for me it was fixed after updating it to lastest version.

17

Same Error .. any one found solution ?

18

I am also getting the same error after adding the definations and upgraded the version to 4.2.0 but the issue is not resolved. Please let me know if anyone found the solution of this.

19

I am also getting the same error after adding the definations and upgrade the version to 4.2.0 but the issue is not resolved. Please let me know if you have any solution for it.

20

Same error. Worked fine Friday. Got the error today. Updated CLI to 4.2.0 but no change.

UPDATE: Cleared my ~/.cache/shopify and ~/.config/shopify folders and after that it worked.

21

I have no idea what this error means, but I’m getting it as well. Last Friday it was working fine, and now I randomly get this error while I’ve literally not changed anything. How is it possible that without changing anything this can suddenly fail?

22

3.93.0 seems to be the oldest version this isn’t occurring on.
(Although upgrading breaks our current oauth method)