nodejs/node · error · Error

${this.constructor.providerEntity} must be specified in the

Error message

${this.constructor.providerEntity} must be specified in the format group/project or group/subgroup/project

What it means

Thrown by GitLab trust provider's validateEntity() when the project path passed via --project (or inferred from package.json) does not contain at least one '/'. The provider expects GitLab's 'group/project' or 'group/subgroup/project' namespace form so it can build a valid blob URL and a project_path claim. Because the check only counts segments, a bare project name or an empty string trips it.

Source

Thrown at deps/npm/lib/commands/trust/gitlab.js:59

    trustDefinitions['allow-publish'],
    trustDefinitions['allow-stage-publish'],
    // globals are alphabetical
    globalDefinitions['dry-run'],
    globalDefinitions.json,
    globalDefinitions.registry,
    globalDefinitions.yes,
  ]

  getEntityUrl ({ providerHostname, file, entity }) {
    if (file) {
      return new URL(`${entity}/-/blob/HEAD/${file}`, providerHostname).toString()
    }
    return new URL(entity, providerHostname).toString()
  }

  validateEntity (entity) {
    if (entity.split('/').length < 2) {
      throw new Error(`${this.constructor.providerEntity} must be specified in the format group/project or group/subgroup/project`)
    }
  }

  validateFile (file) {
    if (file !== path.basename(file)) {
      throw new Error('GitLab CI/CD pipeline file must be just a file not a path')
    }
  }

  static optionsToBody (options) {
    const { file, project, environment } = options
    const trustConfig = {
      type: 'gitlab',
      claims: {
        project_path: project,
        // this looks off, but this is correct
        /** The ref path to the top-level pipeline definition, for example, gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main. Introduced in GitLab 16.2. This claim is null unless the pipeline definition is located in the same project. */
        ci_config_ref_uri: {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass the full namespace: `--project group/my-project` (or `group/subgroup/my-project`).
2. Fix the package.json `repository` field to a GitLab URL or `gitlab:group/project` shorthand so inference yields two+ segments.
3. Verify the resolved entity with `npm trust gitlab ... --dry-run` before the real call; inspect what entity was inferred.

Example fix

// before
npm trust gitlab --file .gitlab-ci.yml --project my-app
// after
npm trust gitlab --file .gitlab-ci.yml --project my-group/my-app

const assertGitlabEntity = (entity) => {
  if (typeof entity !== 'string' || entity.split('/').filter(Boolean).length < 2) {
    throw new TypeError(`GitLab project must be group/project or group/subgroup/project, got: ${JSON.stringify(entity)}`)
  }
}
// call before invoking the trust command programmatically
assertGitlabEntity(process.env.NPM_TRUST_PROJECT)

const isNamespacedGitlabPath = (v) =>
  typeof v === 'string' && v.split('/').filter(Boolean).length >= 2

try {
  await trustGitlab.exec([...])
} catch (err) {
  if (/group\/project/i.test(err.message)) {
    // prompt user for the full namespaced path and retry
  } else { throw err }
}

When it happens

Trigger: Running `npm trust gitlab --file .gitlab-ci.yml --project my-project` (no group), or passing an empty `--project`, or having a package.json repository like 'my-project' that resolves to a single-segment hosted-git-info repository used as the inferred project entity. validateEntity is called at the end of flagsToOptions after entity resolution.

Common situations: Copy-pasting just the repo name from GitLab's UI instead of the full namespaced path; a malformed repository string yielding one segment; forgetting the subgroup in deeply nested GitLab projects.

Related errors

• 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
• At least one permission flag is required (--allow-publish, -

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