nodejs/node · error · Error

The `${baseKey}` option is deprecated, and cannot be set in

Error message

The `${baseKey}` option is deprecated, and cannot be set in this way${deprecated}

What it means

Even when a key is a valid config option, if its definition carries a `.deprecated` marker it cannot be set via `npm config set`. The appended deprecation text explains why and points to the supported replacement.

Source

Thrown at deps/npm/lib/commands/config.js:174

        throw this.usageError()
    }
  }

  async set (args) {
    if (!args.length) {
      throw this.usageError()
    }

    const where = this.npm.flatOptions.location
    for (const [key, val] of Object.entries(keyValues(args))) {
      log.info('config', 'set %j %j', key, val)
      const baseKey = key.split(':').pop()
      if (!this.npm.config.definitions[baseKey] && !nerfDarts.includes(baseKey)) {
        throw new Error(`\`${baseKey}\` is not a valid npm option`)
      }
      const deprecated = this.npm.config.definitions[baseKey]?.deprecated
      if (deprecated) {
        throw new Error(
          `The \`${baseKey}\` option is deprecated, and cannot be set in this way${deprecated}`
        )
      }

      if (val === '') {
        this.npm.config.delete(key, where)
      } else {
        this.npm.config.set(key, val, where)
      }

      if (!this.npm.config.validate(where)) {
        log.warn('config', 'omitting invalid config values')
      }
    }

    await this.npm.config.save(where)
  }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Read the appended deprecation message and switch to the named replacement
2. Edit .npmrc manually only if the option still works there (check docs first)
3. Remove the setting entirely if the behavior is now the default

Example fix

# before
npm config set package-lock false

# after (follow the deprecation note; e.g. rely on default lockfile behavior or use --no-package-lock per-command)

const def = npm.config.definitions[baseKey]
if (def && def.deprecated) {
  throw new Error(`Refusing to set deprecated ${baseKey}: ${def.deprecated}`)
}

function isDeprecatedOption(key, definitions) {
  return Boolean(definitions[key.split(':').pop()]?.deprecated)
}

When it happens

Trigger: Setting an option that npm has marked deprecated in the current version (e.g. legacy options superseded by package-lock.json or new flags).

Common situations: Upgrading npm and re-running an old provisioning script; dotfiles that still configure obsolete behavior.

Related errors

• `${baseKey}` is not a valid npm option
• The ${key} option is protected, and cannot be retrieved in t
• Tag name must not be a valid SemVer range: ${defaultTag.trim
• %s: error: no build_file
• Could not automatically locate src directory. This isa temp

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/f9cdb6de1029023d. Report an issue: GitHub.