Backstage catalog "Unable to read url ... 404" in CI

The catalog reads each registered location URL. A 404 means the catalog-info.yaml path is wrong, the branch or repo moved, or the integration cannot access a private location.

What this error means

A catalog import or validation step fails with "Unable to read url, NotFoundError: ... 404 Not Found" for a specific catalog-info.yaml location.

Unable to read url, NotFoundError: {"documentation_url":
"https://docs.github.com/rest","message":"Not Found"} at
https://github.com/acme/repo/blob/main/catalog-info.yaml (404)

Common causes

The location path or branch is wrong

The registered URL points at a file or branch that does not exist (renamed file, deleted branch), so the read 404s.

A private repo without integration access

The location is in a private repository and the integration token cannot read it, which GitHub returns as 404.

How to fix it

Correct the location URL

1. Open the registered location and confirm the file exists at that branch and path.
2. Fix the URL to the current default branch and path.
3. Re-run the catalog read.

catalog:
  locations:
    - type: url
      target: https://github.com/acme/repo/blob/main/catalog-info.yaml

Grant integration access for private repos

Configure the GitHub integration token so the catalog can read private locations instead of getting 404.

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

How to prevent it

• Reference the default branch and current path in locations.
• Configure integration tokens that can read private locations.
• Validate locations in CI so a moved file fails fast.

Related guides