"Unknown user/project config" warnings starting in npm 11.2.0

---Added by npm team---

See this comment #8153 (comment) for the proper way to have package-level config that does not collide with npm config

Summary

When running npm --version, npm issues warnings about some custom configuration keys in my .npmrc. These warnings indicate that the keys will stop working in the next major version of npm.

Environment

node version: v23.9.0
npm version: 11.2.0
Win11

Steps to Reproduce

Create a .npmrc file with the following content:

registry="https://registry.npmmirror.com/"
electron_mirror="https://npmmirror.com/mirrors/electron/"
electron_custom_dir="{{ version }}"
electron_builder_binaries_mirror="http://npmmirror.com/mirrors/electron-builder-binaries/"

Run the command:
```
npm --version
```

Observe the following warnings:

npm warn Unknown user config "electron_mirror". This will stop working in the next major version of npm.
npm warn Unknown user config "electron_custom_dir". This will stop working in the next major version of npm.
npm warn Unknown user config "electron_builder_binaries_mirror". This will stop working in the next major version of npm.

Expected Behavior
The custom configuration keys should be recognized, or there should be documentation clarifying the correct way to set these options without triggering warnings.

Actual Behavior
The custom keys (electron_mirror, electron_custom_dir, and electron_builder_binaries_mirror) are not recognized by npm, resulting in warning messages about their future deprecation.

Questions

Are these warnings expected with the current configuration, or is there a recommended way to define these custom options?
Will these configurations be supported in future versions of npm, or should they be modified/removed to ensure compatibility?

Additional Context
I am using custom mirror URLs to optimize package and binary downloads. Any guidance or documentation regarding the proper configuration for these settings would be greatly appreciated.

This also applies to things like NODE_OPTIONS and any options that are set for pnpm or other package managers that use .npmrc

On my end:
npm warn Unknown user config "scripts.build". This will stop working in the next major version of npm.

I believe the intention is to stop people from doing exactly that - from abusing npmrc as a way to define non-npm-related environment or configuration variables.

We have the same warnings with cli and env config:

npm run myScript --customVar

npm warn Unknown cli config "--customVar". This will stop working in the next major version of npm.

Will there be a way to whitelist some keys?

My understanding is that only things npm uses will be supported. If you want to pass arguments to the script’s command itself, use -- to separate arguments npm consumes from ones the script’s command consumes.

That will pass arguments only to the last command in case the script is defined like:

"myScript": "command1 && command2"

Is there an easy way to pass parameters to both commands in this case?

an environment variable, i suppose?

@ljharb

Why is this viewed as "abuse"? The 11.2.0 cli documentation clearly states that the config top-level object in package.json can be used to set configuration parameters, as in the example from the documentation:

A "config" object can be used to set configuration parameters used in package scripts that persist across upgrades. For instance, if a package had the following:
{
  "name": "foo",
  "config": {
    "port": "8080"
  }
}
It could also have a "start" command that referenced the npm_package_config_port environment variable.

@ljharb, your suggestion of a workaround, an environmental variable, is actually the exact case that has been broken without explanation.

@wraithgar, since you shipped this change, can you confirm if this is intended behavior? I think if npm is deprecating a top-level object in package.json, the above error messages are not a good (or clear) way to inform the user base.

The package.json#config example is exactly how you want to do this. Those aren't parsed as "npm" config values, those are isolated as "user space" config values for the package. Those are exported as npm_package_config_ and not npm_config so they are not something npm would try to re-parse as its own config.

~/D/s/glob $ npm pkg get config
{
  "foo": "hello world"
}
~/D/s/glob $ npm config ls|grep foo
~/D/s/glob $ npm run env|grep foo
npm_package_config_foo=hello world
~/D/s/glob $ npm -v 
11.2.0

No warnings.

This also applies to things like NODE_OPTIONS and any options that are set for pnpm or other package managers that use .npmrc

These should be unaffected. In .npmrc itself that config is node-options and npm sets that to NODE_OPTIONS in the environment.

I am going to pin this issue for now since there may be more folks who are wondering how to address these warnings. I also added a link to the OP to my comment about package.json#config since that's the solution we are recommending.

I've raised a PR to fix this: #8995

Improved the warning message to include an actionable hint about
.npmrc, along with updated documentation.

As I said before, the problem with using environment variables - besides the practical implications of having to do this on multiple OS - is that these cannot be automatically set when the package is installed as a dependency - and especially in various lambda & server-less environments.

dotenv does not work in this case.

I think that there will be a huge outcry when this feature is removed (just look at the number of comment on this issue which is about the warning).

Me personally, I will wait for this moment, so that, ideally, everyone who is affected can agree on a new universal solution.

If this is not the case, I will re-implement on my own the Node.js way of searching for the parent package.json in order to extract the configuration information from the including package.

The docs PR was not meant to be a complete "closes the issue" fix for this. Sorry about that.

Adding a document is not a solution to this case. The method of configuring environment variables in .npmrc has been used for many years and is widely known among developers. Even though you now regard this design as a flaw and intend to eliminate it, it is extremely common across global industries for widely adopted unofficial de facto standards to later be formalized into official standards.

Simply disabling the practice of setting global variables in .npmrc will only create unnecessary trouble for the vast developer community. Developers will either be forced to adopt far less elegant workarounds or refuse to upgrade Node.js entirely.

As an ancient Chinese saying goes: Water management calls for diversion, not blockage.
I suggest introducing an official field for defining environment variables in places like package.json, for example an "env" field.

feat: detect pnpm/yarn/bun and suggest native dlx in init

chore: release v0.6.2 — package manager detection + dlx hint

It's not clear from the configuring-npm/npmrc document whether a key with an empty, non-existent, null value should be considered a defined key and subject to this warning. For example, consider an entry in the .npmrc file or other sources that simply says myKey=.

Our frustration is that we run a Jenkins CI/CD pipeline that pulls together Groovy snippets from both the shared library and individual jobs, as well as Husky style scripts and the like. It's excruciatingly hard to figure out just where a given key was created but never given a value.

Can the relevant code be updated to just simply ignore empty keys?

npm warn Unknown config is too aggressive — breaks legitimate third-party tool conventions in .npmrc

Background

Our project uses .npmrc to configure both npm and third-party tools (e.g. @electron/get) in a monorepo. This is a long-standing community convention — tools like electron-builder, node-gyp, and node-pre-gyp all document using .npmrc as their configuration entry point.

Our .npmrc includes:

ELECTRON_MIRROR=https://cdn.npmmirror.com/binaries/electron/
ELECTRON_CUSTOM_DIR={{ version }}

These are read by @electron/get at install time to redirect binary downloads to a mirror — a standard practice especially in regions where GitHub is slow or blocked.

Problem

Since npm 10.x, every single npm command now prints:

npm warn Unknown env config "ELECTRON_CUSTOM_DIR". This will stop working in the next major version of npm.
npm warn Unknown project config "ELECTRON_MIRROR". This will stop working in the next major version of npm.

This is disruptive noise on every npm run, npm install, etc.

Why this is unreasonable

.npmrc is a de-facto shared config file for the Node ecosystem, not npm's private property. Dozens of widely-used tools rely on reading custom keys from it. npm unilaterally deciding to warn on unknown keys ignores years of established convention.
These keys are not typos — they are intentional. The warning assumes the user made a mistake. But there's no way to tell npm "I know what I'm doing, this key is for another tool." There's no escape hatch.
The warning message is misleading. Saying "This will stop working in the next major version" implies the config was doing something for npm — it never was. It works fine for @electron/get and will continue to do so. The warning creates false urgency.
It pollutes CI/CD output and developer terminals, making it harder to spot real warnings.

Suggestion

Add a way to explicitly mark keys as intentional / third-party, e.g.:

  # @suppress-unknown
  ELECTRON_MIRROR=https://...

Or introduce an unknown-key-action = warn | ignore | error config option so projects can opt out of the noise.
At minimum, downgrade from warn to a lower log level that doesn't appear by default.

node-options was already mentioned above but I didn't see any post mentioning the following solution/workaround. Sets the environment variables for all scripts while getting rid of the warnings.

# .npmrc
node-options="--import=data:text/javascript,process.env.ELECTRON_MIRROR='https://custom.electron-mirror.com/';process.env.electron_use_remote_checksums='1'"

In my opinion, this shouldn't have landed without some kind of escape hatch in .npmrc, especially for the global one. Many options exist, like prefixing (x-) or allowing ini [section] syntax that other tools can use. Carving out exceptions for the existing pnpm/yarn fields would also have been courteous (it's a well defined set) as a transitional measure, and those tools could migrate to the prefix/section syntax more incrementally.

Moreover, for anyone who has written a pnpm/yarn-specific field to their global .npmrc (knowingly or unknowingly) npm now breaks unless they remove those old configs (likely breaking other projects non-locally). Seems bad for npm.

Plus the downstream churn this has caused (pnpm v11 moving away from .npmrc/npm_config_) has inconvenienced many developers for the sake of a very dubious win here. I get those are downstream ecosytem changes that npm maintainers do not control, but it was a predictable response from pnpm and could have been avoided.

Apologies for the partial duplication but I created a new issue to discuss the possibility of reverting this pre-v12, because I find that this issue's title isn't reflective of that debate. #9699

i reverted this breaking change 👏

Navigation Menu

Repository navigation

"Unknown user/project config" warnings starting in npm 11.2.0 #8153

44 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

"Unknown user/project config" warnings starting in npm 11.2.0 #8153

Description

Activity

timtucker-dte commented on Mar 10, 2025

Medkhat commented on Mar 11, 2025

spamshaker commented on Mar 11, 2025

ljharb commented on Mar 11, 2025

nikolay-nenkov commented on Mar 12, 2025

ljharb commented on Mar 12, 2025

nikolay-nenkov commented on Mar 12, 2025

ljharb commented on Mar 12, 2025

jimmy-zhening-luo commented on Mar 12, 2025

wraithgar commented on Mar 12, 2025

wraithgar commented on Mar 12, 2025

wraithgar commented on Mar 12, 2025

44 remaining items

umeshmore45 commented on Feb 19, 2026

mmomtchev commented on Feb 23, 2026

wraithgar commented on Feb 23, 2026

ttqftech commented on Apr 2, 2026

hodnett commented on Apr 30, 2026

ethan321222 commented on Jun 12, 2026

DrJonki commented on Jun 12, 2026

colinhacks commented on Jul 2, 2026

reggi commented on Jul 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions