pnpm self-update doesn't respect tags?

[brc-dd]

Verify latest release

• I verified that the issue exists in the latest pnpm release

pnpm version

12.0.0

Which area(s) of pnpm are affected? (leave empty if unsure)

No response

Link to the code that reproduces this issue or a replay of the bug

No response

Reproduction steps

~ ❯ pnpm self-update 12            
Checking for updates...
Switching pnpm from v12.0.0 to v12.0.0...
Packages are cloned from the content-addressable store to the virtual store.
  Content-addressable store is at: /Users/divyansh/Library/pnpm/store/v11
  Virtual store is at:             Library/pnpm/global/v11/10999-18d082b4bcb11548-0/node_modules/.pnpm
.../global/v11/10999-18d082b4bcb11548-0  | Progress: resolved 2, reused 2, downloaded 0, added 2, done
Successfully updated pnpm to v12.0.0

~ ❯ pnpm self-update next-12  
Checking for updates...
Switching pnpm from v12.0.0 to v12.0.0...
Packages are cloned from the content-addressable store to the virtual store.
  Content-addressable store is at: /Users/divyansh/Library/pnpm/store/v11
  Virtual store is at:             Library/pnpm/global/v11/10aaf-18d082bb74624378-0/node_modules/.pnpm
.../global/v11/10aaf-18d082bb74624378-0  | Progress: resolved 2, reused 2, downloaded 0, added 2, done
Successfully updated pnpm to v12.0.0

~ ❯ pnpm self-update 12.1.0 
Checking for updates...
Switching pnpm from v12.0.0 to v12.1.0...
Downloading @pnpm/exe.darwin-arm64@12.1.0: 16.96 MB/16.96 MB, done
Packages are cloned from the content-addressable store to the virtual store.
  Content-addressable store is at: /Users/divyansh/Library/pnpm/store/v11
  Virtual store is at:             Library/pnpm/global/v11/10b62-18d082c10f14f690-0/node_modules/.pnpm
.../global/v11/10b62-18d082c10f14f690-0  | Progress: resolved 2, reused 0, downloaded 2, added 2, done
Successfully updated pnpm to v12.1.0

^ these are running pnpm self-update outside any project in my home directory, on system-wide installation.

Describe the Bug

When using pnpm self-update with a semver or tag, it doesn't seem to pull what that tag currently points to.

Expected Behavior

All three of the commands above should have updated to 12.1.0, but they updated to 12.0.0 when 12.0.0 was already installed.

Which Node.js version are you using?

26.8.0

Which operating systems have you used?

• macOS
• Windows
• Linux

If your OS is a Linux based, which one it is? (Include the version if relevant)

No response

[github-actions[bot]]

Oz triage is running now and will classify this issue and apply one pnpm state: label.

Follow along in Oz: https://oz.warp.dev/runs/01a05178-520d-77d1-9c7f-737495661d12

[github-actions[bot]]

Triage result

• Issue: pnpm self-update doesn't respect tags?` (#14345)
• State: Ready to spec
• Applied label: state: needs design
• Product / parity: Rust pacquet (pnpm/) — the reproduction (store/v11 layout, "Successfully updated pnpm to v...") is the v12 self-update flow implemented in pnpm/crates/cli/src/cli_args/self_update.rs and config_deps.rs::resolve_engine_version. Whether a fix is needed in the TypeScript stack too depends on root cause (see below).
• Rationale: The report is clear: an exact version (self-update 12.1.0) updates correctly, but a semver range (12) and a dist-tag (next-12) both silently no-op back onto the already-installed 12.0.0 even though 12.1.0 exists. This is a distinct symptom from the already-fixed/closed #13883 ("self-update next-12 downgrades from rc.4 to rc.3"), whose fix (excluding the running version from the minimumReleaseAge maturity gate) is already present in config_deps.rs and doesn't explain this case, since the default minimumReleaseAge is disabled unless explicitly configured. Range/tag resolution goes through resolve_engine_version → the npm resolver's conditional-GET metadata cache (fetch_full_metadata_cached.rs, ETag/If-Modified-Since against the registry), while an exact version can resolve without needing the full packument/dist-tags list. That points to either a caching/staleness bug in pnpm's conditional-GET handling, or an upstream npm registry CDN-propagation delay for dist-tags/version lists shortly after a publish (outside pnpm's control) — the two require different fixes (or no fix at all, just documentation) and can't be told apart without deliberately reproducing against a controlled registry/mocked responses and possibly adding diagnostics. Given the repo's very active recent history of subtle, interacting self-update edge cases (minimumReleaseAge, trustPolicy, downgrade guards), a one-pass implementation is risky without first confirming the cache-vs-propagation root cause and, if it's caching, deciding whether self-update should bypass the metadata cache for freshness.
• Next step: Investigate whether next-12/12 reuse a stale cached packument (conditional-GET returning 304 against outdated cached data) versus the registry itself lagging on tag/version-list propagation after a fresh publish; if it's a caching bug, spec out whether self-update should force-bypass the metadata cache when resolving a range/tag (and mirror that decision in the TypeScript stack for parity).

[brc-dd]

If it's because of minimumReleaseAge, can we get some note in the output mentioning the cooldown? Also, if it's because of cache, shouldn't that cache be refreshed when 12.1.0 was installed? If I downgrade from 12.1.0 to 12.0.0 and re-run those commands, they have the same behavior:

[hyunbinseo]

I am experiencing downgrade from 12.2.1 to 12.1.0.

I believe the minimumReleaseAge is being applied when it shouldn't:

The project's minimumReleaseAge, trustPolicy, and ci settings do not affect self-update.

pnpm -v # 12.2.1

pnpm self-update
# Checking for updates...
# The current project is set to use pnpm v12.2.1, which is newer than the "latest" version on the registry (v11.25.0). No update performed. Run "pnpm self-update latest" to downgrade.

pnpm self-update next-12
# Checking for updates...
# The current project has been updated to use pnpm v12.1.0

[brc-dd]

Yeah, I think it's bit unreliable. I've set

alias bump-pnpm='pnpm self-update $(pnpm view pnpm dist-tags.latest-12)'

so that it always gets an explicit version. Alternatively, if you need something generic:

bump-pnpm() {
  local tag="${1:-latest-12}"
  pnpm self-update "$(pnpm view pnpm "dist-tags.$tag")"
}

[Byron2016]

pnpm self-update fails to update from 11.24.0 to 11.25.0 despite latest tag pointing to 11.25.0

pnpm version

11.24.0

Executable path

• Git Bash / MINGW64 on Windows

Description

Running pnpm self-update reports that v11.24.0 is already "latest" and doesn't need an update, even though 11.25.0 has been published and assigned to the latest tag on npm registry.

Expected Behavior

pnpm self-update should detect 11.25.0 as the latest available version and update the currently installed version (11.24.0) to 11.25.0.

Actual Behavior

pnpm self-update outputs:

Checking for updates
The currently active pnpm v11.24.0 is already "latest" and doesn't need an update

[zkochan]

well we were explicitly asked for this behavior. So it is not a bug. You can add pnpm to the global minimumReleaseAgeExclude array to turn the cooldown off for pnpm.

pnpm config set --global --json minimumReleaseAgeExclude '["pnpm"]'

one thing that we could consider is how the explicit pnpm self-update latest command works but then I'd change that for all package too, not just pnpm. So, I'll convert this to a discussion.