Skip to content

fix(release): engine patch updates make unchanged runner ranges uninstallable #1657

Open

Description

@coygeek

Summary

A fresh npm install of an unchanged project on an older runner minor now fails because engine releases within its existing patch ranges require a newer runner minor. Both engines show the same failure. This conflicts with the documented 0.x release policy that breaking changes use a minor bump and that patch ranges receive updates without a package.json edit.

Steps to reproduce

Public reproduction input: the dependency ranges in Expo's with-e2e example. The following reduced fixture was executed without Expo, an app, a device, a model, or credentials.

  1. In an empty directory, write this package.json:
{
  "private": true,
  "devDependencies": {
    "e2e": "~0.21.3",
    "@e2e-dev/mobile": "~0.12.4"
  }
}
  1. With no lockfile or node_modules, run npm install --ignore-scripts --no-audit --no-fund. It exits 1 during dependency resolution.
  2. In another empty directory, use the same fixture with "@e2e-dev/web": "~0.15.3" instead of the mobile engine. The same command exits 1 for the web peer.
  3. Controls: repeat in empty directories with the mobile engine pinned exactly to 0.12.5, or the web engine pinned exactly to 0.15.4. Both installs exit 0. Dependency lifecycle scripts were deliberately disabled; the failure is in resolution before those scripts.

Expected behavior

A patch release selected by an existing engine range should preserve the project's installability with its previously accepted runner range. A release that stops accepting that runner range should use the project's documented breaking-change version boundary. This does not require an engine to claim compatibility with a runner whose exports or contract it cannot use.

Actual behavior

The mobile fixture selects the latest engine patch and exits 1:

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error Found: e2e@0.21.3
npm error Could not resolve dependency:
npm error peer e2e@">=0.22.1 <1" from @e2e-dev/mobile@0.12.6

The web-only fixture also exits 1:

npm error peer e2e@">=0.22.1 <1" from @e2e-dev/web@0.15.5

Published npm metadata shows:

Engine release peerDependencies.e2e
@e2e-dev/mobile@0.12.5 >=0.15.0 <1
@e2e-dev/mobile@0.12.6 >=0.22.1 <1
@e2e-dev/web@0.15.4 >=0.18.0 <1
@e2e-dev/web@0.15.5 >=0.22.1 <1

npm view e2e versions --json contains no stable 0.22.1; the first published stable runner satisfying the new floor is the tested latest runner. Nightlies named 0.22.1-nightly-* exist, but do not satisfy this stable peer range. This is a patch-release compatibility report, not a claim that the peer floor should accept those prereleases or be lowered without checking runtime compatibility.

Runtime or environment

  • Platform: macOS, Apple silicon; Node.js 26.12.1.
  • npm: 12.2.1 and latest 12.2.2; both floating-range fixtures fail on both versions. The exact-engine controls resolve on both, and their package installs pass on the latest npm.
  • Latest stable npm packages checked: e2e 0.23.0, @e2e-dev/mobile 0.12.6, @e2e-dev/web 0.15.5.
  • Source baselines: default branch main at e83fdf9144faf9d8dac810b7a309499d2979fa24; release tags e2e@0.22.0 at cad17c3200ceb5439a261f9c24e6e7ebbf85ddff and e2e@0.23.0 at 5f256928ebe08a8c7126fbc2a83c64a02fb24491. Current main retains the raised engine peer floors.
  • Engine: both @e2e-dev/mobile and @e2e-dev/web; no engine was launched.

Evidence

  • Expected source: CONTRIBUTING.md, Changesets reserves 0.x minor bumps for breaking changes, uses patches for features and fixes, and explicitly explains patch-range updates without a manifest edit. The same policy remains on current main.
  • Failure source: the reduced npm fixtures and output above; the published peer metadata can be checked with npm view @e2e-dev/mobile@0.12.5 peerDependencies, the following mobile patch, and the two web patches in the table.
  • Evidence provenance: observed
  • Local verification: reproduced
  • Reproduction completeness: complete

The floor change is deliberate: the initial locator commit raised both floors and declared patch changesets; the follow-up commit set the current floor. The associated locator PR describes the floor increase, although that PR is closed without a merge; the commits are present in the release history. The mobile changelog and web changelog document the new minimum under Patch Changes.

The engine release guidance says to raise a peer floor when an engine relies on a newer export or contract field. The upgrade command intentionally selects compatible runner/engine sets. Those rules explain the floor and provide an upgrade path, but do not state an exception to the patch-versus-breaking version policy. Exact pins to the preceding engines were verified here as an installation workaround; no test suite was run with them.

Restoration check

The unchanged floating-range fixtures should resolve and install without bypassing peer validation or moving their runner ranges to another minor. The exact-engine controls should remain installable. Any release-policy correction should also ensure that an engine update which drops an accepted runner minor does not enter an existing patch range. Preserve truthful runtime peer requirements; accepting an incompatible graph with --force or --legacy-peer-deps does not restore the contract.

Triage assessment

  • Impact level: P2
  • Assessment status: supported
  • Impact basis: Fresh installs fail for projects that retain an older runner minor while allowing the affected engine patch updates. The two reduced cases fail deterministically at npm resolution; this is bounded to those version combinations.
  • Workaround status: available
  • Workaround basis: Pinning the mobile or web engine to its preceding exact release passes installation with the unchanged runner range and peer validation enabled. This establishes installation only; runtime tests were not run.

Activity

  1. Varshith-Kali commented on Nov 10, 2026

    @Varshith-Kali
    Contributor

    Hi, I would like to work on this. I reproduced the failure: @e2e-dev/mobile@0.12.6 and @e2e-dev/web@0.15.5 both peer on e2e >=0.22.1 <1, and no stable e2e@0.22.1 exists (only nightlies), so a fresh install on e2e ~0.21.3 fails at resolution with ERESOLVE. The floor was raised in #1493 for the doctor hook. I am looking at restoring the pre-#1493 floors with the doctor hook kept working on runners that support it, plus a guard so a patch release cannot raise a peer floor to an unpublished version.

  2. okwasniewski commented on Nov 10, 2026

    @okwasniewski
    Member

    [claude-opus-5-5] automated triage on behalf of @okwasniewski

    Confirmed. mobile 0.12.6 and web 0.15.5 raised their e2e peer floor to >=0.22.1 in patch changesets (#1464, #1493). 0.22.1 was never published, so in practice the floor is 0.23.0, and projects set up with ^0.21.x or ^0.22.0 now fail npm resolution.

    @Varshith-Kali please don't restore the pre-#1493 floors. The floor is mostly correct and isn't only there for the doctor hook:

    The fix belongs in the release checks, not the ranges:

    • if an engine changeset raises its e2e floor past a runner minor that its previous range accepted, it must be a **Breaking:** minor
    • the floor must name a published version (or the runner version in the same release)
    • an engine that starts importing a new e2e/engine export counts as raising the floor

    That probably means extending scripts/check-changeset-bumps.ts or scripts/check-peer-ranges.ts. Affected projects can upgrade the runner to ^0.23.0 (npx e2e upgrade) or pin the previous engine version exactly. Side note: the @e2e-dev/acp peer >=0.21.4 also names a version that was never published.

  3. added
    bugSomething isn't working
    dependenciesPull requests that update a dependency file
    mobileMobile engine (@e2e-dev/mobile)
    webWeb engine (@e2e-dev/web)
    P2Improvement / follow-up
    on Nov 10, 2026
  4. Varshith-Kali commented on Nov 10, 2026

    @Varshith-Kali
    Contributor

    Thanks for the triage, that is clear. I will not restore the floors. I had already built a floor restore before your comment, so I am dropping that and reworking to the release checks you describe: a floor raise past a previously accepted runner minor must be a Breaking: minor, the floor must name a published version, and a new e2e/engine import counts as a raise. I will also fix the @e2e-dev/acp >=0.21.4 floor you flagged, since it names a version that was never published. I will open the reworked change here once the checks pass locally.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Improvement / follow-upbugSomething isn't workingdependenciesPull requests that update a dependency filemobileMobile engine (@e2e-dev/mobile)webWeb engine (@e2e-dev/web)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions