Shopify App Deployment Stuck? Fixing the 'Specification File Required' Error

Hey everyone! As a Shopify migration expert, I spend a lot of time digging through community forums, and I recently stumbled upon a really common, yet incredibly frustrating, issue that many app developers are facing. It's that dreaded message: "At least one specification (.toml OR .json) file is required" when you're trying to deploy or even just develop your Shopify app.

This isn't just a minor hiccup; it's a complete roadblock. Let's dive into a recent discussion from the Shopify Community where a developer, @gjadeau, laid out the problem in detail, and how the community started to chip away at a solution.

The Frustrating 'Specification File Required' Error Explained

Imagine you're diligently working on your Shopify app, everything's building locally, and you're ready to push it live or even just test it with shopify app dev. Then, BAM! You hit this error:

❌ Error
└  At least one specification (.toml OR .json) file is required

See specification requirements:

Or, if you're trying to deploy, you might see something like:

Version couldn't be created.
At least one specification (.toml OR .json) file is required

This is exactly what @gjadeau was experiencing. What made it particularly baffling for them was that it wasn't just happening on one specific app; it was failing on ALL apps, including freshly scaffolded ones using shopify app init. This immediately tells us it's likely not an issue with the app's code itself, but something deeper – perhaps with the local environment, the Shopify CLI, or how the CLI interacts with Shopify's servers.

Another confusing aspect @gjadeau pointed out was that the error message referenced sales channel specifications (https://shopify.dev/docs/apps/build/sales-channels/channel-config-extension#specification-properties), even though their app was an embedded app with Shopify Function extensions, not a sales channel app. This kind of misdirection can send you down a rabbit hole!

Here's a snippet of the detailed log @gjadeau shared, showing the error during 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 │ 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.                                                                       │
│                                                                                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────
╯

It's clear the error happens at the appVersionCreate GraphQL mutation – this is the point where the CLI tries to tell Shopify what your app *is* and what extensions it has. If it can't find the necessary description of your app's components, it throws this error.

The Community's First Line of Defense: Upgrade Your CLI!

The beauty of a strong developer community is that someone often has already walked a similar path. In this case, another user, @LukasEshopGuide, chimed in with a solution that worked for them: upgrading the Shopify CLI to the latest version.

npm install -g @shopify/cli@latest

This is often the first, best step for many CLI-related issues. Shopify's CLI is constantly being updated, and sometimes a bug that causes these kinds of cryptic errors gets patched in a newer release. Even if you think you're on a recent version (like @gjadeau who tried 3.84.1 and 3.93.2), a fresh @latest install can often resolve underlying dependency or caching issues.

Beyond the CLI Upgrade: What Else Can You Do?

If upgrading the CLI doesn't magically fix it for you, don't despair! Based on @gjadeau's detailed report and general Shopify app development knowledge, here are some troubleshooting steps:

1. Double-Check Your CLI Version: After running the upgrade command, verify your current CLI version with shopify version. Make sure it reflects the intended update.

2. Verify Core Configuration Files: Ensure your main shopify.app.toml file is present in your app's root directory and is correctly structured. This file is the blueprint for your app.

3. Inspect Extension Configuration: Since @gjadeau's app used Shopify Functions, it's crucial that each function has its own shopify.function.extension.toml (or similar for other extension types) correctly defined within its respective directory. The shopify.app.toml also needs to correctly reference these extensions.

   • Look at the [[extensions]] array in your shopify.app.toml. Are the path values correct?
   • Is each extension's .toml file complete and valid?

4. Reset Your Local App Configuration: Sometimes, local cached configurations can get out of sync. Try running shopify app dev --reset or shopify app deploy --reset. This forces the CLI to re-authenticate and re-fetch app details, which can clear up inconsistencies.

5. Re-initialize (for new apps): If you're working on a brand-new app and still facing issues, sometimes a clean start helps. Delete your project directory and run shopify app init again. It's a bit drastic, but it ensures no hidden local files are causing problems.

6. Check for Hidden Characters or Encoding Issues: While less common, sometimes invisible characters or incorrect file encodings can corrupt .toml or .json files, making them unreadable by the CLI. Open your configuration files in a robust code editor that can show hidden characters.

7. Detailed Bug Report to Shopify: If you've tried all of the above and are still stuck, it's time to report the issue to Shopify. Include all the details @gjadeau provided: CLI version, Node version, OS, Organization ID, App ID, app type, and verbose logs. The more information you give, the faster their support team can diagnose the problem.

It's a frustrating error because it's so generic, but as we saw with @LukasEshopGuide's experience, often the simplest solution – an CLI upgrade – is the fix. For others, like @gjadeau, it might require a deeper dive into configuration or even reaching out to Shopify support. The key is to be systematic in your troubleshooting. Don't give up, and keep leaning on the community – there's always someone who's faced something similar!