cli [Bug]: "_shopify_essential" could not be defined.

Please confirm that you have:

[x] 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.)
[x] Reproduced the issue in the latest CLI version.

In which of these areas are you experiencing a problem?

Theme

Expected behavior

I'm unsure if this is a CLI upgrade issue, or node upgrade problem. But since upgrading both the first time i run the command shopify theme dev I get an error. On subsequent tries it's fine??

Actual behavior

Error "our development session could not be created because the "_shopify_essential" could not be defined. Please, check your internet"

Verbose output

Paste the output here!

Reproduction steps

Install CLI version 3.67.2 & node version 23.9.0
Run command shopify theme dev
It breaks?
Run it again.. it's fine?

Operating System

Windows 11

Shopify CLI version (`shopify --version`)

3.76.2

Shell

Git Bash

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

23.9.0

What language and version are you using in your application?

N/A

Mar 12 '25 13:03 ceri-waterscreative

Same behaviour for me - it's not user/machine dependent.

Mar 27 '25 10:03 verdant-spark

One developer of my team is having the same problem :/

May 26 '25 09:05 0xtlt

👋 Hey everyone,

Thanks a lot for reporting this issue!

This shouldn’t be happening in the latest version of Shopify CLI, but if you're still facing it, could you please share the output of shopify theme dev --verbose?

In older versions, deleting the development theme with shopify theme delete -d -f would resolve this issue. However, we strongly recommend updating to the latest version instead.

Thanks again for reporting!

May 26 '25 18:05 karreiro

@karreiro It happens so randomly that it's very difficult to run --verbose at the right time but I'll try

May 27 '25 07:05 ceri-waterscreative

As @ceri-waterscreative said, 80% of the times it's working, and sometimes not, but I got those verboses when I had the bug:

(I anonymized the output)

shopify theme dev --verbose
2025-05-26T08:55:39.384Z: Running command theme dev
2025-05-26T08:55:39.386Z: Running system process in background:
  · Command: /Users/USERNAME/.nvm/versions/node/v21.7.3/bin/node /opt/homebrew/bin/shopify notifications list --ignore-errors
  · Working directory: /project/path/

2025-05-26T08:55:39.391Z: Notifications to show: 0
2025-05-26T08:55:39.399Z: Ensuring that the user is authenticated with the Theme API with the following scopes:
[]

2025-05-26T08:55:39.399Z: Ensuring that the user is authenticated with the Admin API with the following scopes for the store store-name.myshopify.com:
[]

2025-05-26T08:55:39.400Z: Getting session store...
2025-05-26T08:55:39.400Z: Validating existing session against the scopes:
[
  "openid",
  "https://api.shopify.com/auth/shop.admin.graphql",
  "https://api.shopify.com/auth/shop.admin.themes",
  "https://api.shopify.com/auth/partners.collaborator-relationships.readonly",
  "https://api.shopify.com/auth/shop.storefront-renderer.devtools",
  "https://api.shopify.com/auth/partners.app.cli.access",
  "https://api.shopify.com/auth/destinations.readonly",
  "https://api.shopify.com/auth/organization.store-management",
  "https://api.shopify.com/auth/organization.apps.manage"
]
For applications:
{
  "adminApi": {
    "scopes": [],
    "storeFqdn": "store-name.myshopify.com"
  }
}

2025-05-26T08:55:39.401Z: - Token validation -> It's expired: false
2025-05-26T08:55:39.401Z: Getting development theme...
2025-05-26T08:55:39.402Z: Sending "Admin" GraphQL request:
  query publicApiVersions {
  publicApiVersions {
    handle
    supported
    __typename
  }
}

With variables:
{}

With request headers:
 - User-Agent: Shopify CLI; v=3.80.7
 - Keep-Alive: timeout=30
 - Sec-CH-UA-PLATFORM: darwin
 - Content-Type: application/json

to https://store-name.myshopify.com/admin/api/unstable/graphql.json
2025-05-26T08:55:39.625Z: Request to https://store-name.myshopify.com/admin/api/unstable/graphql.json completed in 222 ms
With response headers:
 - content-type: application/json; charset=utf-8
 - server-timing: processing;dur=73, graphql;desc="admin/query/other", cfRequestDuration;dur=118.000031
 - x-request-id: *****
    
2025-05-26T08:55:39.625Z: Sending "Admin" GraphQL request:
  query getTheme($id: ID!) {
  theme(id: $id) {
    id
    name
    role
    processing
    __typename
  }
}

With variables:
{
  "id": "gid://shopify/OnlineStoreTheme/*****"
}

With request headers:
 - User-Agent: Shopify CLI; v=3.80.7
 - Keep-Alive: timeout=30
 - Sec-CH-UA-PLATFORM: darwin
 - Content-Type: application/json

to https://store-name.myshopify.com/admin/api/2025-04/graphql.json
2025-05-26T08:55:39.790Z: Request to https://store-name.myshopify.com/admin/api/2025-04/graphql.json completed in 165 ms
With response headers:
 - content-type: application/json; charset=utf-8
 - server-timing: processing;dur=63, graphql;desc="admin/query/other", cfRequestDuration;dur=123.999834
 - x-request-id: *****
    
2025-05-26T08:55:39.795Z: Sending "Admin" GraphQL request:
  query OnlineStorePasswordProtection {
  onlineStore {
    passwordProtection {
      enabled
      __typename
    }
    __typename
  }
}

With request headers:
 - User-Agent: Shopify CLI; v=3.80.7
 - Keep-Alive: timeout=30
 - Sec-CH-UA-PLATFORM: darwin
 - Content-Type: application/json

to https://store-name.myshopify.com/admin/api/2025-04/graphql.json
2025-05-26T08:55:40.007Z: Request to https://store-name.myshopify.com/admin/api/2025-04/graphql.json completed in 212 ms
With response headers:
 - content-type: application/json; charset=utf-8
 - server-timing: processing;dur=64, graphql;desc="admin/query/other", cfRequestDuration;dur=171.000004
 - x-request-id: *****
    
2025-05-26T08:55:40.015Z: Port 9292 is free
2025-05-26T08:55:40.015Z: Ensuring that the user is authenticated with the Theme API with the following scopes:
[]

2025-05-26T08:55:40.015Z: Ensuring that the user is authenticated with the Admin API with the following scopes for the store store-name.myshopify.com:
[]

2025-05-26T08:55:40.015Z: Getting session store...
2025-05-26T08:55:40.015Z: Validating existing session against the scopes:
[
  "openid",
  "https://api.shopify.com/auth/shop.admin.graphql",
  "https://api.shopify.com/auth/shop.admin.themes",
  "https://api.shopify.com/auth/partners.collaborator-relationships.readonly",
  "https://api.shopify.com/auth/shop.storefront-renderer.devtools",
  "https://api.shopify.com/auth/partners.app.cli.access",
  "https://api.shopify.com/auth/destinations.readonly",
  "https://api.shopify.com/auth/organization.store-management",
  "https://api.shopify.com/auth/organization.apps.manage"
]
For applications:
{
  "adminApi": {
    "scopes": [],
    "storeFqdn": "store-name.myshopify.com"
  }
}

2025-05-26T08:55:40.015Z: - Token validation -> It's expired: false
2025-05-26T08:55:40.016Z: Ensuring that the user is authenticated with the Storefront API with the following scopes:
[]

2025-05-26T08:55:40.016Z: Getting session store...
2025-05-26T08:55:40.016Z: Validating existing session against the scopes:
[
  "openid",
  "https://api.shopify.com/auth/shop.admin.graphql",
  "https://api.shopify.com/auth/shop.admin.themes",
  "https://api.shopify.com/auth/partners.collaborator-relationships.readonly",
  "https://api.shopify.com/auth/shop.storefront-renderer.devtools",
  "https://api.shopify.com/auth/partners.app.cli.access",
  "https://api.shopify.com/auth/destinations.readonly",
  "https://api.shopify.com/auth/organization.store-management",
  "https://api.shopify.com/auth/organization.apps.manage"
]
For applications:
{
  "storefrontRendererApi": {
    "scopes": []
  }
}

2025-05-26T08:55:40.016Z: - Token validation -> It's expired: false
2025-05-26T08:55:40.017Z: Sending HEAD request to URL https://store-name.myshopify.com/?preview_theme_id=***********&_fd=0&pb=0
With request headers:
 - X-Shopify-Shop: store-name.myshopify.com
 - User-Agent: Shopify CLI; v=3.80.7

2025-05-26T08:55:40.148Z: Request to https://store-name.myshopify.com/?preview_theme_id=***********&_fd=0&pb=0 completed in 132 ms
With response headers:
 - cache-control: private, max-age=0, no-store, no-cache, must-revalidate, post-check=0, pre-check=0
 - content-type: text/html; charset=UTF-8
 - server-timing: chlray;desc="945c0e0b6809f144", cfRequestDuration;dur=6.999969
    
2025-05-26T08:55:40.149Z: Failed to obtain _shopify_essential cookie.

       -Request ID: unknown

       -Body: 
2025-05-26T08:55:40.149Z: Verifying if theme with id *********** has required files...
2025-05-26T08:55:40.149Z: Sending "Admin" GraphQL request:
  query getThemeFileBodies($id: ID!, $after: String, $filenames: [String!]) {
  theme(id: $id) {
    files(first: 250, after: $after, filenames: $filenames) {
      nodes {
        filename
        size
        checksumMd5
        body {
          __typename
          ... on OnlineStoreThemeFileBodyText {
            content
            __typename
          }
          ... on OnlineStoreThemeFileBodyBase64 {
            contentBase64
            __typename
          }
          ... on OnlineStoreThemeFileBodyUrl {
            url
            __typename
          }
        }
        __typename
      }
      userErrors {
        filename
        code
        __typename
      }
      pageInfo {
        hasNextPage
        endCursor
        __typename
      }
      __typename
    }
    __typename
  }
}

With variables:
{
  "id": "gid://shopify/OnlineStoreTheme/*****",
  "filenames": [
    "layout/theme.liquid",
    "config/settings_schema.json"
  ],
  "after": null
}

With request headers:
 - User-Agent: Shopify CLI; v=3.80.7
 - Keep-Alive: timeout=30
 - Sec-CH-UA-PLATFORM: darwin
 - Content-Type: application/json

to https://store-name.myshopify.com/admin/api/2025-04/graphql.json
2025-05-26T08:55:40.334Z: Request to https://store-name.myshopify.com/admin/api/2025-04/graphql.json completed in 185 ms
With response headers:
 - content-type: application/json; charset=utf-8
 - server-timing: processing;dur=83, graphql;desc="admin/query/other", cfRequestDuration;dur=141.999722
 - x-request-id: *****
    
2025-05-26T08:55:40.335Z: Theme with id *********** has required files.
╭─ error ────────────────────────────────────────────────────────────────────────╮
│                                                                                │
│  Your development session could not be created because the                     │
│  "_shopify_essential" could not be defined. Please, check your internet        │
│  connection.                                                                   │
│                                                                                │
│  To investigate the issue, examine this stack trace:                           │
│    at sessionEssentialCookie                                                   │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:205551)           │
│    at processTicksAndRejections (node:internal/process/task_queues:95)         │
│    at async getStorefrontSessionCookies                                        │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:205527)           │
│    at async getStorefrontSessionCookiesWithVerification                        │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:207063)           │
│    at async fetchDevServerSession                                              │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:207054)           │
│    at async initializeDevServerSession                                         │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:207044)           │
│    at async dev                                                                │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:209798)           │
│    at run (opt/homebrew/lib/node_modules/@shopify/cli/dist/index.js:209986)    │
│    at _run                                                                     │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/chunk-5AFYDRV4.js:175320)  │
│    at runCommand                                                               │
│    (opt/homebrew/lib/node_modules/@shopify/cli/dist/chunk-5AFYDRV4.js:174145)  │
│                                                                                │
╰────────────────────────────────────────────────────────────────────────────────╯

2025-05-26T08:55:40.372Z: Running system process:
  · Command: npm prefix
  · Working directory: /project/path/

2025-05-26T08:55:40.572Z: Obtaining the dependency manager in directory /Users/USERNAME/Desktop/***********/***********...
2025-05-26T08:55:40.929Z: Request to https://monorail-edge.shopifysvc.com/v1/produce completed in 178 ms
With response headers:
 - x-request-id: *****
    
2025-05-26T08:55:40.929Z: Analytics event sent: {
  "command": "theme dev",
  "time_start": 1748249739384,
  "time_end": 1748249740370,
  "total_time": 986,
  "success": false,
  "cli_version": "3.80.7",
  "ruby_version": "",
  "node_version": "21.7.3",
  "is_employee": false,
  "uname": "darwin arm64",
  "env_ci": false,
  "env_plugin_installed_any_custom": false,
  "env_plugin_installed_shopify": "[\"@shopify/cli\"]",
  "env_shell": "zsh",
  "env_device_id": "*****",
  "env_cloud": "localhost",
  "env_package_manager": "pnpm",
  "env_is_global": true,
  "env_auth_method": "device_auth",
  "env_is_wsl": false,
  "cmd_app_warning_api_key_deprecation_displayed": false,
  "cmd_all_timing_network_ms": 915,
  "cmd_all_timing_prompts_ms": 0,
  "cmd_all_launcher": "unknown",
  "cmd_all_topic": "theme",
  "cmd_all_plugin": "@shopify/theme",
  "cmd_all_force": false,
  "cmd_all_verbose": true,
  "cmd_all_path_override": true,
  "cmd_all_path_override_hash": "496d786e58e8ffa918dee0385aa48ab84a8cb29b",
  "cmd_all_last_graphql_request_id": "*****",
  "cmd_all_timing_active_ms": 70,
  "cmd_all_exit": "unexpected_error",
  "user_id": "*****",
  "request_ids": ["*****"],
  "args": "--verbose (redacted)",
  "error_message": "Your development session could not be created because the \"_shopify_essential\" could not be defined. Please, check your internet connection.",
  "env_plugin_installed_all": "[\"@shopify/cli\"]",
  "metadata": "{\"extraPublic\":{},\"extraSensitive\":{}}"
}
2025-05-26T08:55:40.938Z: Reporting unhandled error to Bugsnag: Your development session could not be created because the "_shopify_essential" could not be defined. Please, check your internet connection.
2025-05-26T08:55:41.409Z: Running system process:
  · Command: npm prefix
  · Working directory: /project/path/

2025-05-26T08:55:41.578Z: Obtaining the dependency manager in directory /Users/USERNAME/Desktop/***********/***********...

May 27 '25 13:05 0xtlt

🎉 Thanks! Will let you know if I come across it again.

Jun 19 '25 09:06 ceri-waterscreative

👋 Hey folks,

This issue has been resolved and the fix will be included in the next minor release.

If you'd like to access the fix immediately, you can install the following build:

pnpm i -g @shopify/[email protected]

Thank you, everyone, for reporting!

Jun 19 '25 09:06 karreiro

cli cli copied to clipboard

[Bug]: "_shopify_essential" could not be defined.

Please confirm that you have:

In which of these areas are you experiencing a problem?

Expected behavior

Actual behavior

Verbose output

Reproduction steps

Operating System

Shopify CLI version (shopify --version)

Shell

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

What language and version are you using in your application?

cli
cli copied to clipboard

Shopify CLI version (`shopify --version`)

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