nodejs/node · error · Error

${providerEntity} must be specified with ${entityKey} option

Error message

${providerEntity} must be specified with ${entityKey} option

What it means

Thrown by TrustCommand.flagsToOptions when no entity was resolved AND matchPkg is false (the positional package name given does NOT match the package.json name), i.e. the user is configuring trust for a different package than the one in the cwd, so package.json repository inference is intentionally skipped, and without an explicit entity flag there is nothing to use. The message drops the 'inferred from package.json' clause because that path is not applicable here.

Source

Thrown at deps/npm/lib/trust-cmd.js:302

    if (invalidPkgJsonProviderType) {
      const message = this.warnString`Repository in package.json is not a ${providerEntity}`
      if (!flags[entityKey]) {
        throw new Error(message)
      } else {
        warnings.push(message)
      }
    } else {
      if (mismatchPkgJsonRepository) {
        warnings.push(this.warnString`Repository in package.json (${git.repository}) differs from provided ${providerEntity} (${entity})`)
      }
    }

    if (!entity && matchPkg) {
      throw new Error(`${providerEntity} must be specified with ${entityKey} option or inferred from the package.json repository field`)
    }
    if (!entity) {
      throw new Error(`${providerEntity} must be specified with ${entityKey} option`)
    }

    this.validateEntity(entity)

    return {
      values: {
        package: pkgName,
        file: flags.file,
        [entityKey]: entity,
        ...(flags.environment && { environment: flags.environment }),
      },
      fromPackageJson: {
        [entityKey]: usedRepositoryInPkgJson,
        package: usedPkgNameFromPkgJson,
      },
      warnings: warnings,
      urls: {
        package: this.getFrontendUrl({ pkgName }),

View on GitHub (pinned to 1b2de5e052)

Solutions

Provide the entity flag: `--project group/proj` (gitlab) / `--repo owner/repo` (github).
If you intended to use the local package's repository, drop the mismatched positional so matchPkg becomes true.
Run the command from within the target package's own checkout so its package.json applies.

Example fix

// before
npm trust gitlab other-pkg --file .gitlab-ci.yml --allow-publish
// after
npm trust gitlab other-pkg --file .gitlab-ci.yml --project group/proj --allow-publish

Defensive patterns

Strategy: validation

Validate before calling

if (!entity && !matchPkg) {
  throw new Error(`Targeting a different package (${positional}); pass --${entityKey} explicitly since package.json inference is skipped`)
}

Type guard

const hasEntityForForeignPkg = (entity, flags, entityKey) =>
  Boolean(entity) || Boolean(flags && flags[entityKey])

Try / catch

try {
  await createConfigCommand(...)
} catch (err) {
  if (/must be specified with .* option$/i.test(err.message)) {
    // pass the explicit entity flag matching the foreign package's repo, then retry
  } else { throw err }
}

Prevention

When configuring trust for a package other than the cwd's, always pass the entity flag.
Run trust commands from within the target package's checkout when possible.
Document which entity each script targets to avoid mismatched positionals.

When it happens

Trigger: Running `npm trust gitlab other-pkg --file .gitlab-ci.yml --allow-publish` (positional differs from local package.json name) without `--project`. Since positional != pkgJsonName, matchPkg is false; entity stays undefined; this branch fires.

Common situations: Configuring trust for a package you don't have checked out locally; cross-package scripting where cwd differs from the target package.

Related errors

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