badges/shields · info · NotFound

branch not found

Error message

branch not found

What it means

The GitLab pipeline status service throws this NotFound error when the GitLab API response carries a message/status of 'unknown', meaning no pipeline exists for the requested ref. The library renders a 'branch not found' badge rather than an empty status.

Source

Thrown at services/gitlab/gitlab-pipeline-status.service.js:90

  static render({ status }) {
    return renderBuildStatusBadge({ status })
  }

  async fetch({ project, branch, baseUrl }) {
    return this._requestSvg({
      schema: badgeSchema,
      url: `${baseUrl}/${decodeURIComponent(
        project,
      )}/badges/${branch}/pipeline.svg`,
      httpErrors: httpErrorsFor('project not found'),
    })
  }

  static transform(data) {
    const { message: status } = data
    if (status === 'unknown') {
      throw new NotFound({ prettyMessage: 'branch not found' })
    }
    return { status }
  }

  async handle(
    { project },
    { gitlab_url: baseUrl = 'https://gitlab.com', branch = 'main' },
  ) {
    const data = await this.fetch({
      project,
      branch,
      baseUrl,
    })
    const { status } = this.constructor.transform(data)
    return this.constructor.render({ status })
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

1. Fix the branch/ref name in the badge URL to match an existing branch
2. Run a pipeline on the target branch (push a commit or trigger manually)
3. Point the badge at the default branch or use the project-level pipeline status
4. Update or remove stale README badges for deleted branches

Example fix

// before
[![build](https://img.shields.io/gitlab/pipeline/user/repo/master)]
// after (repo default branch is now main)
[![build](https://img.shields.io/gitlab/pipeline/user/repo/main)]

const project = encodeURIComponent(repo)
const branches = await (await fetch(`https://gitlab.com/api/v4/projects/${project}/repository/branches`)).json()
if (!branches.some(b => b.name === branch)) console.warn(`Branch ${branch} does not exist`)

const hasPipeline = (d) => d != null && d.message !== 'unknown' && typeof d.status === 'string'

try {
  const { status } = GitlabPipelineStatus.transform(data)
} catch (e) {
  if (e.prettyMessage === 'branch not found') {
    // fall back to default branch badge
  } else throw e
}

When it happens

Trigger: Requesting a pipeline status badge for a branch name that does not exist in the GitLab repository (typo, renamed/deleted branch), or a ref that has never had a pipeline run.

Common situations: Default branch renamed from master to main while the badge still points at the old name; feature branch merged and deleted leaving a stale README badge; project uses merge request pipelines only so branch ref has no pipeline.

Related errors

• build pipeline not found
• build pipeline not found
• not set up
• no jobs found
• job not found

AI-assisted analysis of badges/shields@766fd8bc89 (2026-08-30). Data as JSON: /api/errors/81daec3e0530a57d. Report an issue: GitHub.