badges/shields · error · NotFound

build pipeline not found

Error message

build pipeline not found

What it means

The Azure DevOps build status handler fetches the build list, validates it against buildSchema, and requires exactly one matching build (count !== 1) before resolving stage/job results. When the count is anything else it throws NotFound 'build pipeline not found', meaning the requested definition/branch combination did not resolve to a single build.

Source

Thrown at services/azure-devops/azure-devops-build.service.js:209

        definitions: definitionId,
        $top: 1,
        statusFilter: 'completed',
        'api-version': '5.0-preview.4',
      },
    }
    if (branch) {
      options.searchParams.branchName = `refs/heads/${branch}`
    }

    const { count, value } = await this.fetch({
      url,
      options,
      schema: buildSchema,
      httpErrors,
    })

    if (count !== 1) {
      throw new NotFound({ prettyMessage: 'build pipeline not found' })
    }

    const result =
      stage || job
        ? await this.getStageOrJobResult(
            organization,
            projectId,
            value[0].id,
            stage,
            job,
            httpErrors,
          )
        : value[0].result
    const status = this.constructor.resultMap[result] || result
    return renderBuildStatusBadge({ status })
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Verify the definitionId, project, and organization in the badge URL.
  2. URL-encode the branch parameter correctly (e.g. branch=refs/heads/main).
  3. Ensure the pipeline has at least one build and that it is accessible (public or with a valid token).
  4. Update the badge after pipelines are deleted or moved to another project.

Example fix

// before
.../build/myorg/myproj/7?branch=main
// after
.../build/myorg/myproj/7?branch=refs%2Fheads%2Fmain
Defensive patterns

Strategy: validation

Validate before calling

const branch = encodeURIComponent('refs/heads/main')
const res = await fetch(
  `https://dev.azure.com/${org}/${project}/_apis/build/builds?definitions=${defId}&branchName=${branch}&api-version=6.0`
)
if ((await res.json()).count !== 1) throw new Error('Pipeline/branch combo has no build')

Try / catch

try {
  return await buildStatusBadge(params)
} catch (e) {
  if (e instanceof NotFound) return renderBadge('pipeline not found')
  throw e
}

Prevention

When it happens

Trigger: Requesting the azure-devops build status badge where the build list API returns count !== 1 for the given definition and branch filter — an invalid definitionId, a branch with no builds, or an inaccessible project yields zero results.

Common situations: Badge URL pointing at a deleted or renamed pipeline; misspelled branch parameter (branch names must be URL-encoded, e.g. refs/heads/main); private pipelines without auth returning empty counts; querying before the first build ever ran.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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