[BUG] npm deprecate fails with "deprecations must be strings" once any version is already deprecated

[MrRefactoring]

Is there an existing issue for this?

Related, but closed without a root cause: #2282, #3449, #3838. #2282 has a 2023 comment reporting it is still broken. This issue supplies the mechanism and a reproduction that does not involve the CLI.

Current Behavior

npm deprecate fails with 400 Bad Request - deprecations must be strings whenever the package already has at least one deprecated version.

The first deprecation on a package with nothing deprecated always succeeds. Every deprecation after that fails, permanently, until all deprecations are cleared again.

$ npm deprecate "jira.js@>=5.0.0-0 <5.0.0" "Development snapshot, not for use."
npm notice deprecating jira.js@5.0.0-dev20250313212005 with message "..."
...
npm error code E400
npm error 400 Bad Request - PUT https://registry.npmjs.org/jira.js - deprecations must be strings

Observed sequence on one package, in order:

command	versions already deprecated	result
npm deprecate 'jira.js@<5.0.0' "…" (83 versions)	0	success
npm deprecate 'jira.js@<4.0.0' "" (undeprecate 83)	83	success
npm deprecate 'jira.js@>=4.1.1-0 <4.1.1' "…" (1 version)	0	success
npm deprecate 'jira.js@>=5.0.0-0 <5.0.0' "…" (32 versions)	1	E400
npm deprecate 'jira.js@>=5.3.1-0 <5.3.1' "…" (1 version)	1	E400

The undeprecate step succeeds because an empty string is still a string.

Expected Behavior

Deprecating a version leaves deprecations on other versions untouched, and succeeds regardless of how many versions are already deprecated.

Root cause

lib/commands/deprecate.js fetches the packument with ?write=true, mutates it, and PUTs the whole document back:

const packument = await npmFetch.json(uri, {
  ...this.npm.flatOptions,
  spec: p,
  query: { write: true },
})

const versions = Object.keys(packument.versions)
  .filter(v => semver.satisfies(v, spec, { includePrerelease: true }))

for (const v of versions) {
  packument.versions[v].deprecated = msg
}

return otplease(this.npm, this.npm.flatOptions, opts => npmFetch(uri, {
  ...opts, spec: p, method: 'PUT', body: packument, ignoreBody: true,
}))

The ?write=true view of the packument does not carry deprecated at all. Both requests below were made within the same minute, against the same package:

$ curl -s 'https://registry.npmjs.org/jira.js' | \
    jq '[.versions[] | select(.deprecated)] | length'
40

$ curl -s -H "authorization: Bearer $TOKEN" 'https://registry.npmjs.org/jira.js?write=true' | \
    jq '[.versions[] | select(.deprecated)] | length'
0

So the document PUT back implicitly clears every deprecation the package already had. The registry rejects that with deprecations must be strings — presumably because the removed entries arrive as undefined rather than a string.

This is not CLI-specific. Reproduced with a plain PUT, no npm involved: taking the ?write=true document, setting deprecated on a single version and PUTting it back returns

HTTP 400
{"success":false,"error":"deprecations must be strings"}

Re-adding the pre-existing deprecated values into the same document before the PUT makes it succeed, which confirms the mechanism.

Steps To Reproduce

These steps are reconstructed from the mechanism, not run against a fresh
package — everything above was observed on a real package with 145 published
versions, and I did not want to publish a throwaway package to confirm the
minimal case. Please treat this section as the expected minimal reproduction
rather than a verified one.

1. Publish a package with at least three versions.
2. npm deprecate 'pkg@1.0.0' "first" — expected to succeed.
3. npm deprecate 'pkg@2.0.0' "second" — expected to fail with E400 deprecations must be strings.
4. npm deprecate 'pkg@<9.9.9' "" to clear, after which step 2 succeeds again.

What is measured and what is inferred

Measured directly:

• the five command outcomes in the table above, in that order;
• the two curl counts (40 vs 0) against the same package, same minute;
• the plain PUT reproducing 400 deprecations must be strings with no npm involved;
• the same PUT succeeding once the pre-existing deprecated values are merged back in.

Inferred:

• that the registry rejects the request because the dropped entries arrive as
  undefined — the error string is the only evidence for the "why", and the
  server-side check is not visible from here;
• the minimal reproduction steps above.

Suggested fix

Either of:

• merge the existing deprecations into the packument before the PUT — read them from the public packument, or from the ?write=true document once the registry includes them; or
• have the registry treat an absent deprecated as unchanged rather than cleared, so a partial document cannot silently drop deprecations.

The first is fixable in the CLI alone.

Environment

npm: 11.13.0
node: v26.1.0
OS: macOS 15 (darwin arm64)
registry: https://registry.npmjs.org

Package used: jira.js (145 versions, 40 deprecated at time of writing).

[MrRefactoring]

Re-reading my own report, I buried the most important part: the primary defect is on the registry side, not in the CLI. The "Suggested fix" section above reads as though this were a CLI bug, which risks parking it in a queue where it cannot be fixed. Correcting that here.

Which side owns which link

1. Registry. GET /:package?write=true returns a document that does not contain deprecated at all. This view exists precisely so that a client can read a document, modify it and write it back — and it loses data on read. This is the primary defect.
2. CLI. lib/commands/deprecate.js trusts the document it received, mutates it, and PUTs the whole thing back. Were the write view complete, this code would be correct — it has worked for years. The weakness is real, but secondary.
3. Registry. It rejects the resulting PUT with 400 deprecations must be strings rather than treating an absent deprecated as unchanged. Ironically, that rejection is the only thing preventing silent mass data loss: without it, every npm deprecate would quietly wipe every earlier deprecation on the package.

Fixing (1) alone makes npm deprecate work with no CLI change at all.

The CLI does have a safer pattern available

npm owner in this same repository does not round-trip the whole document — it PUTs only {_id, _rev, maintainers}, exactly the fields it changes. Regardless of what the registry does, don't write back data you never received seems like a reasonable invariant for deprecate too. I'm happy to open a PR for that if the team wants it; I'd just rather not paper over a registry defect if it's going to be fixed at the source.

Measured vs inferred, restated — it matters for routing

Measured: 40 deprecated versions in the public packument vs 0 in the ?write=true document, same package, same minute; the five command outcomes in the table above, in that order; a plain PUT of the write document rejected with 400; the same PUT succeeding once the pre-existing deprecated values are merged back in.

Inferred: that the rejection happens because the dropped entries arrive as undefined rather than as a string. The error text is the only evidence for the "why" — the string deprecations must be strings does not appear in any public repository, so the server-side check isn't visible from here.

Request

Please route this to the registry team, or point me at the right channel and I'll take it there. A support ticket with the same content is already filed via npmjs.com/support under "There is a problem with the npm registry".