nodejs/node · error · Error

pipeline-definition-id is required

Error message

pipeline-definition-id is required

What it means

Thrown by the CircleCI trust provider's `flagsToOptions` when the `--pipeline-definition-id` flag is missing or empty. CircleCI's OIDC trust model binds to a pipeline definition, so its UUID is mandatory.

Source

Thrown at deps/npm/lib/commands/trust/circleci.js:135

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

    const orgId = flags['org-id']
    const projectId = flags['project-id']
    const pipelineDefinitionId = flags['pipeline-definition-id']
    const vcsOrigin = flags['vcs-origin']
    const contextIds = flags['context-id']

    // Validate required flags
    if (!orgId) {
      throw new Error('org-id is required')
    }
    if (!projectId) {
      throw new Error('project-id is required')
    }
    if (!pipelineDefinitionId) {
      throw new Error('pipeline-definition-id is required')
    }
    if (!vcsOrigin) {
      throw new Error('vcs-origin is required')
    }

    // Validate formats
    this.validateUuid(orgId, 'org-id')
    this.validateUuid(projectId, 'project-id')
    this.validateUuid(pipelineDefinitionId, 'pipeline-definition-id')
    this.validateVcsOrigin(vcsOrigin)
    if (contextIds?.length > 0) {
      for (const contextId of contextIds) {
        this.validateUuid(contextId, 'context-id')
      }
    }

    return {
      values: {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass `--pipeline-definition-id <uuid>` with the CircleCI pipeline definition UUID.
2. Locate it in CircleCI under the project's pipeline settings; must be a UUID.
3. If your CircleCI setup predates pipeline definitions, consult CircleCI docs to find the equivalent identifier.

Example fix

// before
npm trust circleci mypkg --org-id <uuid> --project-id <uuid> --vcs-origin github.com/o/r
// after
npm trust circleci mypkg --org-id <uuid> --project-id <uuid> --pipeline-definition-id <uuid> --vcs-origin github.com/o/r

function assertRequiredFlag(flags, name) {
  if (!flags[name]) throw new Error(`${name} is required`)
  return flags[name]
}
assertRequiredFlag(flags, 'pipeline-definition-id')

function hasPipelineDefinitionId(flags) {
  return Boolean(flags && flags['pipeline-definition-id'])
}

When it happens

Trigger: `flags['pipeline-definition-id']` is falsy during required-flag validation (checked after project-id).

Common situations: Newer CircleCI config where pipeline definitions are first-class and the user only knows the project id; omitting the flag in CI templates copied from older examples.

Related errors

• org-id is required
• project-id is required
• vcs-origin is required
• vcs-origin must not include a scheme (e.g., use 'github.com/
• vcs-origin must be in format 'provider/owner/repo'

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