nodejs/node · error · Error

${providerFile} must be specified with the file option

Error message

${providerFile} must be specified with the file option

What it means

Thrown by TrustCommand.flagsToOptions when `--file` was not provided (flags.file is falsy). The pipeline file is a required input: it becomes the ci_config_ref_uri claim and is the core of a trusted publishing config. The check runs right after the package-name guard.

Source

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

    let entitySource

    if (flags[entityKey]) {
      entity = flags[entityKey]
      entitySource = 'flag'
    } else if (!invalidPkgJsonProviderType && git?.repository) {
      entity = git.repository
      entitySource = 'package.json'
    }
    const mismatchPkgJsonRepository = matchPkg && git && entity !== git.repository
    const usedRepositoryInPkgJson = entitySource === 'package.json'

    const warnings = []
    if (!pkgName) {
      throw new Error('Package name must be specified either as an argument or in package.json file')
    }

    if (!flags.file) {
      throw new Error(`${providerFile} must be specified with the file option`)
    }
    if (!flags.file.endsWith('.yml') && !flags.file.endsWith('.yaml')) {
      throw new Error(`${providerFile} must end in .yml or .yaml`)
    }

    this.validateFile?.(flags.file)

    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})`)
      }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Add `--file <pipeline-file>`, e.g. `--file .gitlab-ci.yml`.
2. Confirm the filename is correct with `ls` in the repo root.
3. Run with `--usage` to see the required options for the provider.

Example fix

// before
npm trust gitlab --project g/p --allow-publish
// after
npm trust gitlab --file .gitlab-ci.yml --project g/p --allow-publish

if (!flags.file) {
  throw new Error('Trust config requires --file pointing to the pipeline definition')
}

const hasFileFlag = (flags) =>
  Boolean(flags && typeof flags.file === 'string' && flags.file.length > 0)

try {
  await createConfigCommand(...)
} catch (err) {
  if (/must be specified with the file option/i.test(err.message)) {
    // ask user for the pipeline filename, set flags.file, retry
  } else { throw err }
}

When it happens

Trigger: Any `npm trust <provider>` create invocation without `--file`. Note the `file` Definition is required:true for GitLab, but flagsToOptions guards defensively because not all providers enforce required at parse time identically.

Common situations: Forgetting the flag; assuming the default `.gitlab-ci.yml` is implied (it is not); typo in the flag name.

Related errors

• ${this.constructor.providerEntity} must be specified in the
• GitLab CI/CD pipeline file must be just a file not a path
• Package name must be specified either as an argument or in t
• Package name must be specified either as an argument or in t
• ID of the trusted relationship to revoke must be specified w

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