[Bug]: `shopify app dev` provides cryptic error message and fails

[vfonic]

Please confirm that you have:

• Searched existing issues to see if your issue is a duplicate. (If you’ve found a duplicate issue, feel free to add additional information in a comment on it.)
• Reproduced the issue in the latest CLI version.

In which of these areas are you experiencing a problem?

App

Expected behavior

The message clearly mentions what the error is, why it failed, and hopefully links to the documentation for further information.

The error simply outputs the scope name. It's a new scope that I'm trying to add to the app, as per documentation:
https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrder

I'm not even sure if this scope is the issue.

I've already requested access to all functionalities within "API access requests" page, except for "Access payment mandate scopes", which looks irrelevant to the error I'm seeing here.

Actual behavior

11:47:36 │               app-preview │ ❌ Error
11:47:36 │                app_access │ └  read_marketplace_fulfillment_orders

Verbose output

Verbose output

> shopify app dev -s xxxxxx -c shopify.app.local.toml --use-localhost
╭─ info ───────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  Using shopify.app.local.toml for default values:                            │
│                                                                              │
│    • Org:             Xxxx Org                                               │
│    • App:             Xxxx App                                               │
│    • Dev store:       xxxxxx.myshopify.com                                   │
│    • Update URLs:     No                                                     │
│                                                                              │
│   You can pass `--reset` to your command to reset your app configuration.    │
│                                                                              │
│   Note: `--use-localhost` is not compatible with Shopify features which      │
│  directly invoke your app (such as Webhooks, App proxy, and Flow actions),   │
│  or those which require testing your app from another device (such as POS).  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

11:47:31 │               app-preview │ Preparing app preview on xxxxxx.myshopify.com
11:47:31 │                  graphiql │ GraphiQL server started on port 3457
11:47:31 │                     proxy │ Proxy server started on port 3458 with certificate
.shopify/localhost.pem
11:47:31 │ xxxxxx-bu │ Building function xxxxxx-business...
11:47:31 │ xxxxxx-bu │ Building GraphQL types...
11:47:31 │                   xxx2-xxx │ Building function xxx2-xxx...
11:47:31 │                   xxx2-xxx │ Building GraphQL types...
11:47:31 │ 200-dollar-order-shipping │ Build successful
11:47:33 │                   xxx2-xxx │ (node:42374) [DEP0040] DeprecationWarning: The `punycode` module is
deprecated. Please use a userland alternative instead.
11:47:33 │                   xxx2-xxx │ (Use `node --trace-deprecation ...` to show where the warning was
created)
11:47:33 │ xxxxxx-bu │ (node:42373) [DEP0040] DeprecationWarning: The `punycode` module is
deprecated. Please use a userland alternative instead.
11:47:33 │ xxxxxx-bu │ (Use `node --trace-deprecation ...` to show where the warning was
created)
11:47:33 │ xxxxxx-bu │ Bundling JS function...
11:47:33 │                   xxx2-xxx │ Bundling JS function...
11:47:33 │ xxxxxx-bu │ Running javy...
11:47:33 │                   xxx2-xxx │ Running javy...
11:47:33 │                   xxx2-xxx │ Done!
11:47:33 │ xxxxxx-bu │ Done!
11:47:36 │               app-preview │ ❌ Error
11:47:36 │                app_access │ └  read_marketplace_fulfillment_orders

───────────────────────────────────────────────────────────────────────────────────────────────────
│ (d) Dev status │ (a) App info │ (s) Store info │                                         (q) Quit

❌ Error updating app preview


╭─ error ──────────────────────────────────────────────────────────────────────╮
│                                                                              │
│  Failed to start app preview.                                                │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

Reproduction steps

1. Add read_marketplace_fulfillment_orders as per documentation: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrder
2. Run shopify app dev

Operating System

macOS

Shopify CLI version (shopify --version)

3.85.4

Shell

oh my zsh

Node version (run node -v if you're not sure)

v22.12.0

What language and version are you using in your application?

ruby 3.4.4 (2025-05-14 revision a38531fd3f) +PRISM [arm64-darwin24]

[amcaplan]

Hi @vfonic, can you try running again with --verbose? It might help to see:

• where exactly it gets stuck
• whether there's a web request we can look at on our side to understand what happened

[vfonic]

Hi @amcaplan! Thanks for looking into this!

I'm not sure how much of verbose logs I can post here as I see some tokens in the logs as well.

Here's the trimmed down last part of the logs:

mutation CreateAssetURL($sourceExtension: SourceExtension!, $organizationId: ID!) {
  appRequestSourceUploadUrl(
    sourceExtension: $sourceExtension
    organizationId: $organizationId
  ) {

mutation DevSessionCreate($appId: String!, $assetsUrl: String!) {
  devSessionCreate(appId: $appId, assetsUrl: $assetsUrl) {

2025-10-17T13:15:49.348Z: Request to https://app.shopify.com/app_management/unstable/graphql.json completed in 743 ms
2025-10-17T13:15:49.349Z: Subscribed to App Events for shop ID(s) xxxxx
2025-10-17T13:15:49.349Z: Success: true
2025-10-17T13:15:49.349Z: Creating directory at .shopify/logs...
2025-10-17T13:15:18.859Z: Request to https://app.shopify.com/app_management/unstable/organizations/xxxxx/app_logs/poll?cursor=2025-10-17T13%3A15%3A18.041383Z completed in 395

 ⠋ Preparing app preview
 ❌ Error updating app preview

PS I managed to get the access I needed by adding one of the other access scopes instead: https://shopify.dev/docs/api/admin-graphql/latest/objects/FulfillmentOrder