badges/shields · error · NotFound

build pipeline not found

Error message

build pipeline not found

What it means

The Azure DevOps base service fetches the latest completed build for a pipeline definition via the Azure DevOps REST API and validates the response against latestBuildSchema. It then asserts that exactly one build was returned (json.count !== 1); otherwise it throws NotFound 'build pipeline not found'. This means the pipeline definition/branch combination resolved to zero (or ambiguous) builds, so no completed build id can be used.

Source

Thrown at services/azure-devops/azure-devops-base.js:63

        $top: 1,
        statusFilter: 'completed',
        'api-version': '5.0-preview.4',
      },
    }

    if (branch) {
      options.searchParams.branchName = `refs/heads/${branch}`
    }

    const json = await this.fetch({
      url,
      options,
      schema: latestBuildSchema,
      httpErrors,
    })

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

    return json.value[0].id
  }
}

View on GitHub (pinned to 766fd8bc89)

Solutions

  1. Verify the organization, project, and definitionId in the badge URL against your Azure DevOps pipeline.
  2. Check that the pipeline has at least one completed build on the branch being queried.
  3. Ensure the pipeline is visible (public project, or supply a valid PAT) so the API does not return an empty result.
  4. Recreate the badge with the correct definitionId after a pipeline was deleted/recreated.

Example fix

// before
/badge/azure-devops/build/myorg/myproj/999
// after
/badge/azure-devops/build/myorg/myproj/42
Defensive patterns

Strategy: validation

Validate before calling

const res = await fetch(
  `https://dev.azure.com/${org}/${project}/_apis/build/builds?definitions=${defId}&branchName=${branch}&$top=1&api-version=6.0`
)
const data = await res.json()
if (data.count !== 1) throw new Error(`No build found for definition ${defId}`)

Try / catch

try {
  const id = await service.buildId(params)
} catch (e) {
  if (e instanceof NotFound) return renderBadge('unknown pipeline')
  throw e
}

Prevention

When it happens

Trigger: Calling getLatestCompletedBuildId (via the buildId method) with an organization/project/definition combination that yields a build list whose count is not 1 — usually an unknown or deleted pipeline definition, or a definition with no completed builds on the requested branch.

Common situations: Wrong definitionId in the badge URL after a pipeline was deleted and recreated; wrong project or organization name; querying a branch with no completed builds; permission-restricted pipelines returning empty lists; private projects accessed without a token.

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/026958d033a03b81. Report an issue: GitHub.