"shopify hydrogen dev" aborts on startup in a network-restricted environment (@shopify/cli 4.7.1 cancellation race)

[paul-phan]

DRAFT — not posted. For Paul's approval before anything goes to Weaverse/pilot.

Repo: Weaverse/pilot
Title: shopify hydrogen dev aborts on startup in a network-restricted environment (@shopify/cli 4.7.1 cancellation race)

Summary

On Pilot 4a99511d (v2026.9.7), npm run dev exits 1 during startup whenever the environment cannot
reach the npm registry. The failure comes from @shopify/cli's startup version-check path, not from
Pilot code or from Vite/Hydrogen:

> @weaverse/pilot@2026.9.7 dev
> react-router typegen && shopify hydrogen dev --codegen --port "$PORT"
…
[vite] (client) Re-optimizing dependencies because vite config has changed
[vite] (ssr) Re-optimizing dependencies because vite config has changed
Error: The `onCancel` handler was attached after the promise settled.
    at o (node_modules/@shopify/cli/dist/latest-version-LDWU5F7A.js:11:17603)
    at d (node_modules/@shopify/cli/dist/latest-version-LDWU5F7A.js:19:47843)
    at t.<anonymous> (node_modules/@shopify/cli/dist/latest-version-LDWU5F7A.js:19:49069)
    at t.wrapper (node:events:639:12)
    at t.emit (node:events:514:20)
    at t.emit (node:domain:473:12)
    at node_modules/@shopify/cli/dist/latest-version-LDWU5F7A.js:19:37968
    at runNextTicks (node:internal/process/task_queues:65:5)
    at processTimers (node:internal/timers:615:9)

The message is p-cancelable's guard: an onCancel handler is attached to a promise that has
already settled. The frame chain ends in processTimers, so the throw is raised from a timer inside
the version-check/self-upgrade flow, escapes through node:domain, and terminates the CLI process
before the dev server ever listens. The dev server never prints ➜ Local:; the surrounding Miniflare
instance then reports ERR_DISPOSED as a consequence of the teardown.

Environment

• Pilot 4a99511d (v2026.9.7), unmodified lockfile (@shopify/cli 4.7.1; registry latest 4.8.0)
• Node 26.8.2, npm 11.19.1, Debian trixie (node:26-slim), linux/arm64
• Dev command exactly as Pilot defines it, only --port taken from the environment
• No egress to the npm registry; name resolution and outbound TCP are denied by the host

Reproduction

1. npm ci on a machine with network, so node_modules is complete.
2. Remove registry reachability (any of: firewall DROP, firewall REJECT, or no route at all).
3. PORT=3458 npm run dev.

Observed: exits 1 with the trace above. The CLI announces
✨ New version of Shopify CLI available! (4.7.1 → 4.8.0) Now upgrading by running: npm install -g @shopify/cli@latest
when it can read the registry, so the crash sits on the path that learns about / installs a newer CLI.

Notably not the cause

• Denial latency. Measured in the failing environment: a denied TCP connect now returns
  ECONNREFUSED in 3 ms (nftables reject with tcp reset), and the crash still occurs.
  Black-holing (drop) crashes identically.
• CI=1. Set for the process; no effect.
• SHOPIFY_CLI_ENV=development. No effect on the crash in our matrix.
• There is no documented SHOPIFY_CLI_* switch that disables the version check; the only guard in
  the bundle is isPreReleaseVersion(version).

Impact

Any deployment that runs Pilot's dev server without npm-registry access — CI sandboxes, offline
development, restricted-egress hosting — cannot start the storefront at all. It is a hard startup
failure, not a degraded notification.

Suggested fix

Guard the version-check/self-upgrade flow so a failure (or a promise that settles before the
cancellation handler is attached) can never reject into the process: await it with a catch, or
skip it when the registry is unreachable. Pinning @shopify/cli past the race in Pilot's lockfile
would unblock consumers in the meantime.

[paul-phan]

Upstream analysis: the version-check crash is not reachable via env config

Static analysis of @shopify/cli@4.7.1's shipped bundle. No containers, no Docker.

The lookup that crashes is not the one the guards protect

versionToAutoUpgrade() (dist/chunk-4FI2YBRF.js, minified ie) calls f("@shopify/cli", c),
which resolves through chunk-GW4JHUIA.js's export map (Ne as v) to:

function Ne(e, n) {                       // checkForNewVersion (sync)
  const a = `npm-package-${e}`;
  const t = W(a)?.value;                  // cacheRetrieve — pure local read
  if (t && new SemVer(n).compare(t) < 0) return t;
}

This is a cache read with no network call. So the earlier theory — that
versionToAutoUpgrade performs the registry lookup before the CI / auto-upgrade guards — is
wrong, and pre-seeding or clearing that cache cannot prevent the crash either.

The networked sibling is:

async function Pe(e, n, { cacheExpiryInHours: a = 0 } = {}) {   // checkForNewVersionOnCLI
  const t = async () => ne(e);                 // ne → dynamic import('./latest-version-*.js')
  try { p = await O(`npm-package-${e}`, t, a * 3600 * 1000); } catch { return; }
  ...
}

Two things matter here:

1. ne() is the only path that loads latest-version-*.js, the module in every crash trace.
2. Pe already wraps it in try { … } catch { return; }. The rejection is caught.

Why the catch does not save it

The crash message is p-cancelable's own invariant, thrown from the constructor's onCancel
registrar:

const o = a => {
  if (!this._isPending) throw new Error("The `onCancel` handler was attached after the promise settled.");
  this._cancelHandlers.push(a);
};

latest-version-*.js contains 22 setTimeout and 1 setInterval. The observed stack bottoms out in
processTimers → runNextTicks, and reaches node:domain:473:12 — i.e. the throw is raised from a
timer callback after the awaited promise already settled, not from the awaited promise itself. A
try/catch around the await cannot catch a throw from a later timer tick; it escapes as an
uncaught exception through the domain and takes the process down.

That also explains every negative result we measured:

• CI=1 — guards sit after the crash point, and Pe is a different caller than ie anyway.
• Fast ECONNREFUSED (3 ms, reject with tcp reset) — changes when the promise settles, not
  whether a stale timer fires afterward. Measured: crash unchanged, deny counters non-zero.
• Silent drop — same crash.

No env lever exists

Full SHOPIFY_CLI_* inventory extracted from the bundle (42 variables). The only ones touching this
area:

• SHOPIFY_CLI_FORCE_AUTO_UPGRADE — forces upgrade; there is no disabling counterpart.
• SHOPIFY_CLI_NO_ANALYTICS — telemetry only; a different code path.
• SHOPIFY_CLI_MAX_REQUEST_TIME_FOR_NETWORK_CALLS / SHOPIFY_CLI_SKIP_NETWORK_LEVEL_RETRY — tune
  request behaviour; they change settle timing, which is exactly what the reset experiment already
  disproved as a lever.

autoUpgradeEnabled is persisted in the CLI's conf store (bg/Pg in chunk-AFT6ABDE.js), not
readable from an env var, and again gates the wrong function.

Conclusion: no configuration reachable from our image prevents this. The fix must be upstream —
either the version check stops registering cancellation handlers after settle, or Pilot pins a CLI
version without the race. That is what Weaverse/pilot#174 asks for, and this analysis should be
added to it.

Consequence for us

The shipped behaviour stands as released: preview auto-start settles to a durable Builder-reported
failed with start_preview available for retry. Nothing further to change in this repository, and
the egress policy correctly remains unmodified.

Skipped: a container experiment per candidate env var. The bundle proves none of them reach the
throw, so each run would only re-measure settle timing we already disproved.

[paul-phan]

Upstream root cause is now filed against the CLI itself: Shopify/cli#8553

That issue carries the full trace. Two corrections to my analysis above, from reading the shipped bundle:

• The trigger is not the CLI auto-upgrade path. versionToAutoUpgrade performs a pure cache read (cacheRetrieve on npm-package-*) with no network call. The networked path is its sibling checkForNewVersionOnCLI, and the caller that reaches hydrogen dev is Hydrogen’s own version check in dist/chunk-IF6EYTHG.js.
• Pinning @shopify/cli forward does not help: dist/latest-version-LDWU5F7A.js is byte-identical (sha256 c493bb882df5b786…) in 4.6.1, 4.7.1, 4.8.0 and the 2026-09-14 nightly.

So there is no fix available from this repository. The realistic options here were replacing shopify hydrogen dev with a direct Vite/react-router invocation (loses MiniOxygen and Oxygen runtime parity) or patching the vendored minified bundle — both worse than waiting for the upstream fix. Keeping this issue open to track adopting a fixed CLI once Shopify ships one.