Shopify CLI 4.9.0 rejects underscores in [[events.subscription]] handles

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

An [[events.subscription]] handle containing an underscore (e.g. product_core) validates and deploys, as it did on 4.8.5. The docs list _ as allowed for Events subscription handles (“alphanumeric, _, -, max 50 characters”).

Actual behavior

Since 4.9.0, shopify app config use and shopify app deploy reject the config with:

Validation error in shopify.app.toml:
[handle]: Handle can only contain alphanumeric characters and hyphens

The same file passes on 4.8.5. Replacing _ with - in the Events handles makes it pass on 4.9.0.

Subscriptions that already exist with underscores can’t be deployed on 4.9.0, which breaks CI that runs npx @shopify/cli@4 app deploy. Is this an intended change? If it is, renaming a handle changes the Shopify-Handle header that apps route deliveries on.

Reproduction steps

  1. Add an Events subscription with an underscore in its handle to shopify.app.toml:
[events]
api_version = "2026-10"

[[events.subscription]]
handle = "product_core"
topic = "Product"
actions = ["update"]
triggers = ["product.title"]
uri = "https://example.com/events"
  1. Run npx @shopify/cli@4.9.0 app config use shopify.app.toml: validation error above.
  2. Run npx @shopify/cli@4.8.5 app config use shopify.app.toml: succeeds.
  3. Change the handle to product-core and run 4.9.0 again: succeeds.

Verbose output

Validation error in shopify.app.toml:

[handle]: Handle can only contain alphanumeric characters and hyphens

Operating system

macOS 15

CLI version

4.9.0 (works on 4.8.5)

Shell

zsh

Nodejs version

22.22.3

What language and version are you using in your application?

TypeScript, Node 22

2

Thanks for the report! It looks like a legit issue, we will work on a fix. Sorry for the inconvenience.

3

It should be fixed in 4.9.1

4

Important thing for software is stability! Year after year Shopify show they do not understand this concept! Shopify it not browser vendor and cli program is not browser! Search on forum here and constant complaint about CLI bug due to new version.

Automatic CLI update exist in v4 and before v4 CLI forcing user to update. This is very bad idea. This post one of so many example why you do not force user to upgrade command-line program! New CLI v4 need to ship with automatic update disabled by default.