nodejs/node · error · Error

`npm rebuild` only supports SemVer version/range specifiers

Error message

`npm rebuild` only supports SemVer version/range specifiers

What it means

Thrown by `npm rebuild` when one of the positional arguments, parsed by `npa`, resolves to a spec type other than `range`, `version`, or `directory` (and is not the bare `*`). npm rebuild only knows how to select installed packages by SemVer range/version or a local directory path; git/tag/alias/remote specs are unsupported.

Source

Thrown at deps/npm/lib/commands/rebuild.js:56

    const arb = new Arborist({
      ...this.npm.flatOptions,
      path: where,
      allowScripts: allowScriptsPolicy,
      // TODO when extending ReifyCmd
      // workspaces: this.workspaceNames,
    })

    if (args.length) {
      // get the set of nodes matching the name that we want rebuilt
      const tree = await arb.loadActual()
      const specs = args.map(arg => {
        const spec = npa(arg)
        if (spec.rawSpec === '*') {
          return spec
        }

        if (spec.type !== 'range' && spec.type !== 'version' && spec.type !== 'directory') {
          throw new Error('`npm rebuild` only supports SemVer version/range specifiers')
        }

        return spec
      })
      const nodes = [...tree.inventory.filter(node => this.isNode(specs, node))]

      await strictAllowScriptsPreflight({ arb, npm: this.npm })
      await arb.rebuild({ nodes })
    } else {
      await arb.loadActual()
      await strictAllowScriptsPreflight({ arb, npm: this.npm })
      await arb.rebuild()
    }

    // Phase 1 advisory: list any packages whose install scripts ran (or
    // would have run) and are not yet covered by allowScripts. Rebuild
    // doesn't go through reifyFinish, so the walker is invoked here.
    const unreviewed = await checkAllowScripts({ arb, npm: this.npm })

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Use a SemVer range or exact version, e.g. `npm rebuild lodash@4.17.21` or `npm rebuild lodash@^4`.
2. Rebuild by package name only (`npm rebuild lodash`) which yields a `*` spec and is allowed.
3. Point at a local directory: `npm rebuild ./my-local-dep`.
4. If you need a git/tag package rebuilt, install it first, then rebuild by name.

Example fix

// before
npm rebuild lodash@next
// after
npm rebuild lodash

const npa = require('npm-package-arg')
function assertRebuildSpec(arg) {
  const spec = npa(arg)
  if (spec.rawSpec === '*') return spec
  if (!['range', 'version', 'directory'].includes(spec.type)) {
    throw new Error(`npm rebuild needs a SemVer range/version or directory, got ${spec.type} for "${arg}"`)
  }
  return spec
}

When it happens

Trigger: Calling `npm rebuild <arg>` where `npa(arg).type` is `git`, `tag`, `alias`, `remote`, or similar, and `.rawSpec !== '*'`.

Common situations: Trying `npm rebuild github:owner/repo`, `npm rebuild pkg@next` (a dist-tag), or `npm rebuild https://...tarball`; copy-pasting an install-style spec into rebuild.

Related errors

• You must specify a tag using --tag when publishing a prerele
• Cannot implicitly apply the "latest" tag because previously
• Missing script: "${event}"${suggestions} To see a list of s
• search must be called with arguments
• ${argv[2]} not recognized

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