feat!: error on unknown configs, flags, and abbreviations by owlstronaut · Pull Request #9276 · npm/cli

owlstronaut · 2026-04-23T20:33:38Z

BREAKING CHANGE: unknown configs in .npmrc, unknown CLI flags, abbreviated flags, and single-hyphen multi-char shorthands now throw instead of warning.

Closesnpm/statusboard#1084.

Unknown configs are now hard errors instead of warnings:

Unknown keys in .npmrc (project/user/global/builtin), aggregated across files
Unknown CLI flags (--bogus)
Abbreviated flags (--dry for --dry-run)
Single-hyphen multi-char flags (-longflag)

Env (npm_config_*) and publishConfig unknowns still warn.

config, help, doctor, completion, and version opt out via static skipConfigValidation = true so npm config fix and friends keep working when .npmrc is broken.

Notable breaks

Legacy top-level auth keys (email, _authToken, _password, username, certfile, keyfile) must be in scoped/nerfdart form. Run npm config fix to migrate.
-j no longer expands to --json. Use --json.

nishantms · 2026-05-21T16:14:07Z

+ 'Run `npm help config` for supported options.',
+ ].join('\n')
+ throw Object.assign(new Error(msg), {
+ code: 'EUNKNOWNCONFIG',


If a user has both bad cli flags and bad keys in .npmrc, they will only see the cli set, fix those, re-run, then see the file set. Worth combining both lists into a single error so it is one trip?

nishantms · 2026-05-21T16:14:20Z

+ }
+
+ // Returns unknown-config entries for a given source ('cli', 'builtin', 'project', 'user', 'global') or all non-env entries when omitted.
+ getUnknownConfigs (where) {


nit — comment says "all non-env entries when omitted" but the filter also drops publishConfig. Maybe "all entries except env and publishConfig"?

nishantms · 2026-05-21T16:16:47Z

+ }
+
+ const command = new TestCommand(npm)
+ t.doesNotThrow(() => command.validateCli(), 'skipConfigValidation bypasses unknown-file-config check')


nit — worth adding a test here that runs a command with NPM_CONFIG_<unknown>=1 set and asserts validateCli does not throw? The carve-out lives in getUnknownConfigs() — a regression test at the base-cmd level would lock it in so the env→warn behavior cannot silently flip if that filter changes.

nishantms

LGTM, no major blocker, few nits

BREAKING CHANGE: unknown configs in .npmrc, unknown CLI flags, abbreviated flags, and single-hyphen multi-char shorthands now throw instead of warning.

Unknown configuration keys in .npmrc files now emit a warning by default, restoring pre-npm-12 behavior, instead of throwing. This reverts the breaking change from 979518d (#9276) for file-based configs. The new `strict-npmrc` config (default false) opts back into treating them as a hard error. Unknown CLI flags and abbreviations continue to error regardless of this setting. The warning flows through the normal display pipeline, so it respects loglevel suppression (e.g. --loglevel=error, --silent). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Unknown configuration keys in .npmrc files now emit a warning by default, restoring pre-npm-12 behavior, instead of throwing. This reverts the breaking change from 979518d (#9276) for file-based configs. The new `strict-npmrc` config (default false) opts back into treating them as a hard error. Unknown CLI flags and abbreviations continue to error regardless of this setting.

## What / Why #9729 reverts the `.npmrc` file-config half of the breaking change from `979518d` (#9276): unknown `.npmrc` configs warn by default again, and the new `strict-npmrc` config opts back into erroring. Unknown CLI flags and abbreviations still throw. The `12.0.0-pre.1` changelog entry still carried the original wording, which claimed unknown `.npmrc` configs now throw. Since release-please aggregates every prerelease `BREAKING CHANGE` note into the eventual stable `v12.0.0` release notes, that stale line would surface (inaccurately) in the 12.0.0 notes. This corrects the wording in place. ## Change Edits the single breaking-changes bullet in the `## [12.0.0-pre.1]` section: > unknown CLI flags, abbreviated flags, and single-hyphen multi-char shorthands now throw instead of warning. (Unknown `.npmrc` configs still warn by default; opt into erroring with the new `strict-npmrc` config.) ## Notes - Manual, targeted edit to an already-released, release-please-generated section — this does not disturb release-please, which derives versions from git tags + commit history and only prepends new sections. Precedent: #8298 (`chore: add contributor to changelog entry`). - Best merged alongside / after #9729 so the corrected note reflects shipped behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…tibility (#35) The first real automated publish attempt (0.1.1-beta.2, all 9 packages) failed identically for every package: EUNKNOWNCONFIG "Unknown cli flag: --git-checks". Root cause confirmed via pnpm/pnpm#9646 and npm/cli#9276: changeset publish always runs pnpm publish --no-git-checks for a pnpm workspace, and pnpm has an open bug that mangles --no-git-checks into a bare --git-checks before forwarding it to the underlying npm call. npm <12 only warned about this; npm 12's breaking change (npm/cli#9276) made unknown CLI flags a hard error, and the later walkback (npm/cli#9729) explicitly excludes CLI flags from the softened behavior - so npm 12 will always hard-fail here regardless of patch version. `npm install -g npm@latest` was pulling in 12.0.1. Pinned to 11.18.0 instead - the newest 11.x release, well past the >=11.5.1 OIDC requirement, but before the breaking change. Nothing was actually published by the failed attempt (confirmed: all 9 packages failed identically before any registry write), so this is a clean retry, not a partial-state cleanup.

owlstronaut requested a review from a team as a code owner April 23, 2026 20:33

owlstronaut force-pushed the feat/error-on-unknown-configs branch 5 times, most recently from a386ace to fd9faf7Compare April 23, 2026 21:09

coderabbitaiBot mentioned this pull request May 13, 2026
chore: add npm supply-chain hardening kitze/apple-crusher#1
Merged

nishantms reviewed May 18, 2026
View reviewed changes

Comment threadworkspaces/config/lib/index.js Outdated
Comment threadlib/base-cmd.js Outdated
Comment threadworkspaces/config/lib/index.js
Comment threadworkspaces/config/lib/index.js

owlstronaut force-pushed the feat/error-on-unknown-configs branch from fd9faf7 to 7c21cdfCompare May 20, 2026 15:48

owlstronaut requested a review from a team as a code owner May 20, 2026 15:48

owlstronaut requested a review from nishantms May 20, 2026 15:53

nishantms reviewed May 21, 2026
View reviewed changes

nishantms previously approved these changes May 21, 2026
View reviewed changes

feat!: error on unknown configs, flags, and abbreviations
8d584bc
BREAKING CHANGE: unknown configs in .npmrc, unknown CLI flags, abbreviated flags, and single-hyphen multi-char shorthands now throw instead of warning.

owlstronaut dismissed nishantms’s stale review via 8d584bcMay 21, 2026 18:17

owlstronaut force-pushed the feat/error-on-unknown-configs branch from 7c21cdf to 8d584bcCompare May 21, 2026 18:17

nishantms approved these changes May 21, 2026
View reviewed changes

owlstronaut merged commit 979518d into latestMay 21, 2026
33 checks passed

owlstronaut deleted the feat/error-on-unknown-configs branch May 21, 2026 18:36

github-actionsBot mentioned this pull request May 21, 2026
chore: release 12.0.0-pre.1 #9387
Merged

cursorBot mentioned this pull request Jun 2, 2026
ci(cli): add CLI smoke matrix workflow (M7, REQ-4.1 to REQ-4.5) rjmurillo/ai-agents#2232
Merged

coderabbitaiBot mentioned this pull request Jun 10, 2026
Add supply chain security policy with npm cooldown tjackiet/bitbank-lab-mcp-legacy#630
Merged

npm-cli-bot mentioned this pull request Jun 23, 2026
deps: upgrade npm to 12.0.0-pre.1 nodejs/node#64096
Closed

reggi mentioned this pull request Jul 7, 2026
feat: warn instead of error on unknown .npmrc configs #9729
Merged

reggi mentioned this pull request Jul 8, 2026
chore: clarify unknown-config breaking change note in changelog #9733
Merged

coderabbitaiBot mentioned this pull request Jul 23, 2026
feat: add new security extras for npm, uv, and mise (2026-07-23 scan) HikaruEgashira/pmsec#45
Merged

SayantanCode mentioned this pull request Jul 26, 2026
Pin release.yml's npm to 11.18.0, avoiding a real pnpm/npm 12 incompatibility SayantanCode/vayo#35
Merged
4 tasks

coderabbitaiBot mentioned this pull request Aug 22, 2026
fix(update): recover npm 12 self-updates lidge-jun/opencodex#2383
Merged
7 tasks

Navigation Menu

Uh oh!

feat!: error on unknown configs, flags, and abbreviations - #9276

feat!: error on unknown configs, flags, and abbreviations#9276
owlstronaut merged 1 commit into
latestfrom
feat/error-on-unknown-configs

owlstronaut commented Apr 23, 2026•
edited
Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nishantmsMay 21, 2026

Uh oh!

nishantmsMay 21, 2026

Uh oh!

nishantmsMay 21, 2026

Uh oh!

nishantms left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

owlstronaut commented Apr 23, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Notable breaks

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nishantmsMay 21, 2026

Choose a reason for hiding this comment

Uh oh!

nishantmsMay 21, 2026

Choose a reason for hiding this comment

Uh oh!

nishantmsMay 21, 2026

Choose a reason for hiding this comment

Uh oh!

nishantms left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

owlstronaut commented Apr 23, 2026•
edited
Loading