Fix npm ERESOLVE: Firebase prerelease peer conflict

TL;DR#

When npm reports a Firebase Functions release candidate as the package it found, a broad peer minimum can still reject it. In the original conflict, firebase-functions-test required >=2.0.0, which excludes 4.0.0-rc.0 under normal prerelease matching. Select a compatible stable SDK release, update the lock file through npm, and verify a clean install. Bypassing peer checks does not make the release candidate satisfy that requirement.

The original Cloud Functions deployment report followed a Functions SDK update. The same dependency mismatch was reproduced on 9 October 2026 in a disposable Docker container running Node 26.10.0 and npm 12.2.0. These lines are from that reproduction:

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree

The diagnostic names the selected SDK:

npm error Found: firebase-functions@4.0.0-rc.0

And the package refusing it:

npm error peer firebase-functions@">=2.0.0" from firebase-functions-test@0.2.3

The historical question uses the older npm ERR! prefix. The package names, selected version and rejected peer range are the useful part; match those against your own output before applying this explanation.

Why it happens#

Two requirements govern the SDK in this example. The application requests a release candidate, while its test helper requests a compatible Functions peer. The published test helper manifest confirms that second requirement. A peer dependency expresses a relationship with the application's installed package, rather than asking npm to hide an unrelated SDK version inside the helper. npm documents that relationship in its peerDependencies reference.

The suffix is decisive. A release candidate sorts above older major versions, but sorting versions and deciding whether a range admits them are separate operations. The node-semver prerelease rules describe the extra condition: a prerelease needs a comparator that explicitly includes a prerelease with the same major, minor and patch tuple. The ordinary stable minimum in the helper has no such comparator.

The root project's ^4.0.0-rc.0 requirement, shown in the historical report, admits that release candidate. Its peer's >=2.0.0 requirement does not. Satisfying the first range therefore cannot establish compatibility with the second. The alternative stable version npm prints in a conflict report is evidence of its resolution attempt; it is not a deployment or migration recommendation.

This was checked separately with semver 7.8.5, the registry's current semver release at the time of testing:

ordering: 4.0.0-rc.0 > 2.0.0 = true
4.0.0-rc.0 satisfies >=2.0.0: false
4.0.1 satisfies >=2.0.0: true

That gives a precise diagnosis: the failure concerns prerelease admission, even though the numeric minimum appears permissive. A missing file, cached tarball or Firebase authentication token is not needed to produce this conflict.

Check your own peer conflict#

Paste the complete conflicting-dependency portion of your npm output to inspect the selected version and peer requirement together. The tool runs in your browser; nothing is sent.

Fix#

1. Inspect the functions application's requirements. From the Firebase project root, enter the functions source directory containing its package manifest. For the standard functions directory:

cd functions
npm pkg get dependencies devDependencies
npm ls firebase-functions firebase-functions-test firebase-admin

The listing can exit with an error on the broken tree; keep the version and invalid-peer information it provides. A root web application can have a different manifest, so running the command above its functions directory may inspect the wrong dependency tree. Compare the helper version against the one in the failing installation log.

2. Read the installed helper's peer range and the candidate SDK's metadata. For the historical conflict, the exact registry queries are:

npm view firebase-functions-test@0.2.3 peerDependencies --json
npm view firebase-functions@4.0.0-rc.0 version peerDependencies deprecated --json

For a project using newer packages, query those exact versions instead. An old answer's peer minimum does not describe every later helper. For example, test helper 3.5.0 requires a stable Functions version at least 4.9.0, and also declares Admin and Jest peers. Changing the Functions SDK alone cannot fix an independently incompatible Admin version.

3. Select a stable release within every applicable peer range. Read the current metadata before choosing an update:

npm view firebase-functions version peerDependencies engines deprecated --json
npm view firebase-functions-test version peerDependencies engines deprecated --json
npm view firebase-admin version engines deprecated --json

On the test date, Functions 7.4.0 and test helper 3.5.0 both admit Admin 13. A separate fresh installation of those packages with Admin 13.6.1 passed peer resolution and a subsequent clean install. Those package versions were not flagged deprecated in the registry. This verifies dependency installation; it does not establish that an existing application's function definitions or tests survive a major SDK upgrade.

For a project already using that compatible Admin and helper combination, the following SDK update is a concrete example:

npm install --save-exact firebase-functions@7.4.0

Review the application's migration requirements and run its tests before deploying. If your Admin or helper requirement differs, establish its intersection first rather than copying this example. The current Admin release was 14.5.0 during research: Functions 7.4.0 admits it, but test helper 3.5.0's Admin range ends at major 13. Independently installing every package's latest version would therefore introduce a different peer conflict. The Admin 13 test fixture is not a recommendation to downgrade an application already on Admin 14.

Prove the release candidate is the only changed input#

The following is a historical reproduction fixture, for an empty disposable directory. It is not a production dependency baseline. It uses published packages, keeps the Admin and helper versions constant, and begins without a lock file:

{
  "name": "firebase-prerelease-peer-fixture",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "firebase-admin": "11.11.1",
    "firebase-functions": "4.0.0-rc.0"
  },
  "devDependencies": {
    "firebase-functions-test": "0.2.3"
  }
}

Save that as package.json and run:

npm install --ignore-scripts --no-audit --no-fund

With npm 12.2.0, installation exits with the peer conflict quoted above. The fixture has no existing lock file to become stale, and the failed installation did not create one. This negative control matters: repeatedly deleting a lock file cannot change the fact that the selected prerelease fails the helper's peer range.

Change only the Functions version in the fixture to stable 4.0.1 and run the same installation command again. In the container, installation succeeded; listing the three Firebase packages and running npm ci also succeeded. The 4.0.1 manifest does not carry a deprecation marker. Stable 4.0.0 was deliberately avoided because its registry record marks it deprecated. This experiment establishes the range mechanism while keeping the old SDK versions out of the production repair advice.

Lifecycle scripts and the audit request were disabled in both halves of the experiment to isolate dependency installation. Neither command used a peer bypass. Application build scripts, Firebase deployment and runtime behaviour were not tested by this fixture.

Verify the fix#

After updating the actual application's manifest through npm, inspect the resulting tree and check that its saved lock supports a fresh installation:

npm ls firebase-functions firebase-functions-test firebase-admin
npm ci

The Firebase packages should have compatible installed versions, and the clean installation should finish without a peer-resolution failure. npm ci uses the saved lock and refuses a manifest mismatch; it also removes an existing dependency installation before starting. Keep the updated manifest and lock together in the change you deploy. A successful local installation is a dependency check, so run the application's existing build and tests before checking deployment.

If the next failure changes to Missing: X from lock file, follow the Firebase Functions lock-file mismatch diagnosis. That page addresses a lock generated under different peer-resolution settings. Here, the original failure was reproduced before any lock existed.

When a prerelease is intentional#

If a package maintainer deliberately supports this exact release candidate, the peer declaration can explicitly include it. The original answer suggests the union >=2.0.0 || 4.0.0-rc.0. The corresponding semver probe returned:

4.0.0-rc.0 satisfies >=2.0.0 || 4.0.0-rc.0: true
4.0.0-rc.0 satisfies >=2.0.0-0: false

Adding a prerelease marker to an unrelated lower bound does not admit every later release candidate. Admission stays tied to the comparator's base tuple under normal matching. A union naming the candidate makes the intended exception explicit, but a satisfied range is still a declaration of intended compatibility, not proof that the helper works with that SDK. Consumers cannot fix a published helper's contract by editing their own unrelated root range. Prefer a maintained helper release that explicitly supports the required SDK, or have its maintainer validate and publish the changed peer declaration.

npm's error message mentions force and legacy-peer-deps. The npm configuration reference explains that the latter ignores peer dependencies; force can permit conflicting peers in the root project. Neither changes the original range's meaning. An installation completed by bypassing that contract therefore fails to verify this repair.

Once installation succeeds, a module-loading failure needs its own evidence. If a changed SDK exposes ERR_PACKAGE_PATH_NOT_EXPORTED, inspect the public imports using the package exports diagnosis. If a Firebase web application instead reports webpack's Default condition should be last one, use the Firebase exports ordering explanation. These messages concern how installed packages are loaded; the prerequisite for this page's repair remains a stable dependency tree whose declared peers agree.

Further reading: Fix "c(...) is not a function" on Firebase SSR deploy.