Shopify App Deployment Fix: Solving the 'Specification File Required' Error
Hey there, fellow Shopify enthusiasts and app developers!
Ever hit that frustrating wall where you're trying to deploy your brilliant new Shopify app or even just run it locally for development, and the command line throws a cryptic error at you? You're not alone! We recently saw a great discussion in the Shopify Community that perfectly captures one of these head-scratching moments, and it's worth diving into because the solution is often simpler than you'd think.
The Mystery of the Missing Specification File
Our community member, @gjadeau, kicked off a thread detailing a persistent issue: their Shopify app deployment was failing with the error message: "At least one specification (.toml OR .json) file is required". What made this particularly perplexing was that it wasn't just happening on an existing, complex app. As @gjadeau pointed out, it was happening on all apps, even freshly scaffolded ones using shopify app init!
The error message itself, referencing sales channel specifications and a link to https://shopify.dev/docs/apps/build/sales-channels/channel-config-extension#specification-properties, was also a bit misleading. @gjadeau confirmed their app was an embedded app with Shopify Function extensions (like product_discounts and validation), not a sales channel app. This kind of misdirection can really send you down the wrong rabbit hole!
Here's a snippet of what @gjadeau saw when trying to run shopify app dev, which also failed with the same "specification file" error:
➜ nex-tep-shopify-discounts-architect git:(main) ✗ shopify app dev
╭─ info ──────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ Using shopify.app.nex-tep-discounts-architect.toml for default values: │
│ │
│ • Org: Wetrust Interactive S.L. │
│ • App: Nex-tep Discounts Architect │
│ • Dev store: percko-3oum4rl7.myshopify.com │
│ • Update URLs: Yes │
│ │
│ You can pass --reset to your command to reset your app configuration. │
│ │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────╯
15:17:39 │ remix │ Running pre-dev command: “npx prisma generate”
15:17:39 │ app-preview │ Preparing app preview on percko-3oum4rl7.myshopify.com
15:17:39 │ graphiql │ GraphiQL server started on port 3457
15:17:39 │ proxy │ Proxy server started on port 49290
15:17:39 │ discount-architect-valida │ Building function discount-architect-validator…
15:17:39 │ discount-architect-valida │ Building GraphQL types…
15:17:39 │ discount-architect-auto │ Building function discount-architect-auto…
15:17:39 │ discount-architect-auto │ Building GraphQL types…
15:17:39 │ discount-architect-code │ Building function discount-architect-code…
15:17:39 │ discount-architect-code │ Building GraphQL types…
15:17:40 │ discount-architect-code │ Bundling JS function…
15:17:40 │ discount-architect-auto │ Bundling JS function…
15:17:40 │ discount-architect-valida │ Bundling JS function…
15:17:40 │ discount-architect-auto │ Running javy…
15:17:40 │ discount-architect-code │ Running javy…
15:17:40 │ discount-architect-valida │ Running javy…
15:17:41 │ discount-architect-code │ Done!
15:17:41 │ discount-architect-auto │ Done!
15:17:41 │ discount-architect-valida │ Done!
15:17:42 │ remix │ Prisma schema loaded from prisma/schema.prisma
15:17:42 │ remix │ Datasource “db”: SQLite database “dev.sqlite” at “file:dev.sqlite”
15:17:42 │ remix │
15:17:42 │ remix │ 1 migration found in prisma/migrations
15:17:42 │ remix │
15:17:42 │ remix │
15:17:42 │ remix │ No pending migrations to apply.
15:17:42 │ remix │ ➜ Local: http://localhost:49293/
15:17:42 │ remix │ ➜ Network: use --host to expose
15:17:43 │ app-preview │ ❌ Error
15:17:43 │ app-preview │ └ At least one specification (.toml OR .json) file is required
15:17:43 │ app-preview │
15:17:43 │ app-preview │ See specification requirements:
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
│ (d) Dev status │ (a) App info │ (s) Store info │ (q) Quit
❌ Error updating app preview
╭─ error ─────────────────────────────────────────────────────────────────────────────────────────────╮
│ │
│ Failed to start app preview. │
│ │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────
╯The Simple, Yet Powerful, Fix from the Community
Thankfully, the Shopify developer community is quick to help! Another helpful member, @LukasEshopGuide, chimed in with a solution that often works wonders for these kinds of CLI-related hiccups: upgrading the Shopify CLI to its latest version.
It's amazing how many seemingly complex issues can be resolved by simply ensuring your development tools are up-to-date. The Shopify platform is constantly evolving, with new features, bug fixes, and compatibility improvements being rolled out regularly. An older CLI version might not fully understand the latest app structure or deployment requirements, leading to errors like the one @gjadeau encountered.
How to Resolve the 'Specification File Required' Error
If you're facing this "At least one specification (.toml OR .json) file is required" error during your Shopify app development or deployment process, here’s what you should do:
-
Open your terminal or command prompt. Make sure you're in an environment where
npmis accessible. -
Run the upgrade command: This command will globally update your Shopify CLI to the very latest stable version available.
npm install -g @shopify/cli@latestThis command tells
npm(Node Package Manager) to install the@shopify/clipackage globally on your system, specifically requesting the@latestversion. This ensures you're running with all the most recent patches and features. -
Verify the upgrade (optional but recommended): After the installation finishes, you can check your CLI version to confirm it's updated:
shopify versionCompare this to the previous version you had. @gjadeau mentioned trying CLI versions
3.84.1and3.93.2, so if you were on one of those, you'd expect a higher number. -
Retry your app command: Once the CLI is updated, navigate back to your app's root directory (if you weren't there already) and try the command that was failing, such as:
shopify app deployshopify app dev
In many cases, just like for @LukasEshopGuide, this simple upgrade will resolve the issue, allowing your app to deploy or run locally without a hitch. It seems the underlying problem was indeed related to how the CLI was interpreting or validating the app's structure or its extensions (like Shopify Functions) at the time of the appVersionCreate GraphQL mutation.
Why Keeping Your Tools Updated Matters
This scenario is a fantastic reminder of why it's so important to keep your development environment—especially command-line tools like the Shopify CLI—regularly updated. The Shopify platform is constantly evolving, and the tools we use to build on it need to keep pace. What works perfectly one day might encounter a new validation check or a changed API requirement the next. Staying current minimizes these kinds of frustrating, time-consuming debugging sessions.
A huge shout-out to @gjadeau for providing such detailed logs and environment information, which makes troubleshooting so much easier, and to @LukasEshopGuide for pinpointing the fix! It's these kinds of community interactions that make developing on Shopify such a collaborative and supportive experience. Hopefully, this insight saves you some precious development time next time you encounter a similar roadblock!