Antora "content source ... not found" in CI
Antora reads content sources (repository URL, branches/tags, and start_path) from the playbook. When a source URL is unreachable or the referenced branch, tag, or start_path does not exist, the build cannot aggregate content.
What this error means
antora fails with "the branches/tags reference 'X' not found" or "the start path 'Y' does not exist" for a content source in the playbook.
antora
error: the branches reference 'v2.0' not found in https://gitlab.com/acme/docs.git
(content source url: https://gitlab.com/acme/docs.git)Common causes
A branch, tag, or URL that does not exist
The playbook names a branch/tag or repository URL that is not present or reachable, so Antora cannot clone the content.
A wrong start_path
The start_path (or start_paths) points to a directory without an antora.yml, so the component cannot be found.
How to fix it
Correct the content source in the playbook
- Verify the repository URL is reachable from CI.
- Set branches/tags to references that exist.
- Point start_path at the directory containing antora.yml.
antora-playbook.yml
content:
sources:
- url: https://gitlab.com/acme/docs.git
branches: [main, v1.0]
start_path: docsProvide credentials for private sources
If the source is private, supply a token so Antora can clone it in CI.
Terminal
git config --global url."https://oauth2:${TOKEN}@gitlab.com/".insteadOf "https://gitlab.com/"How to prevent it
- Reference branches and tags that actually exist.
- Point start_path at a directory with antora.yml.
- Provide credentials for private content sources in CI.
Frequently asked questions
What causes ""reference not found""?
The playbook names a branch/tag or repository URL that is not present or reachable, so Antora cannot clone the content.
How do I fix "reference not found"?
Correct the content source in the playbook
Related guides
Hugo "module ... not found" (Hugo Modules) in CIFix Hugo "module X not found" in CI - a Hugo Module (often a theme) could not be fetched because Go was missi…
Read the Docs build failed installing requirements in CIFix Read the Docs builds that fail while installing requirements - the python.install step did not point at t…
MkDocs "contains a link ... not found among documentation files" (strict) in CIFix MkDocs "contains a link to X which is not found in the documentation files" in CI - a relative link point…