Troubleshooting

Antora reports problems through its logger, and three settings decide how much you see and whether the build fails.

Source: Antora docs: Log failure level

The practical consequence is that a CI job that only runs npx antora antora-playbook.yml passes even when the site has broken links. A stricter job reads:

Source: Antora docs: Log failure level

The next listing is the real output of a build that contained a broken xref, run with that command. The site was written and the exit code was 2.

Every message names the logger (antora, asciidoctor, @antora/content-aggregator, @antora/content-classifier), the file and the content source, including the branch and whether it was read from the worktree or from the Git database. Use that source line to know which branch of which repository holds the faulty file: a fix on the wrong branch is the most common reason an error "does not go away".

The diagram summarises where each problem on this page appears in the build.

The figure follows one build from the playbook to the published folder; the leaves are the messages described below.

Antora only treats a folder as a component version when it contains an antora.yml. If the file is missing at a start path, the build stops at once:

The message names the reference (branch, tag or worktree) that was being read, which matters when the file exists on one branch and not on another: a pattern that selects many branches can fail on an old branch that predates the docs. The usual causes are:

The component version descriptor itself, its required name and version keys and the nav list, is described in the component version descriptor page.

Source: Antora docs: Component version descriptor

start_path (or start_paths) tells Antora in which folder of the repository the antora.yml lives. A mismatch produces one of two opposite messages, depending on which side is wrong. In the first reproduction the documentation stayed at the repository root while the playbook said start_path: docs:

In the second the files were moved into docs/ but the playbook had no start_path, so Antora looked for antora.yml at the root and printed the message from the previous section. Setting start_path: docs made the build succeed. A misspelled value (doc instead of docs) gives the same "does not exist" message as the first case.

Source: Antora docs: Content source start path

start_paths takes a list of folders or glob patterns. A pattern that matches nothing does not fail on its own: the build only stops when none of the patterns match, with the message no start paths found in /work/pocket-units-docs/repo (branch: main <worktree>). A typo in one entry of a list can therefore silently drop a component. Check the generated build/site for the component folders you expect.

A related silent case is a branch pattern that matches no branch. Antora builds a site without that content and exits with code 0. The only hint is an informational message, which is hidden at the default log level:

Run with --log-level=info to see it. The same applies to a tag pattern. When a freshly added content source does not show up in the site, this message is the first thing to look for. Related messages for sources that cannot be read at all are fatal and specific, for example Local content source does not exist: /work/pocket-units-docs/no-such-repo (url: ./no-such-repo).

A component version is identified by the pair of name and version in antora.yml. When two references that are selected by the playbook declare the same pair, Antora merges them into one component version and then finds the same file twice. In the reproduction the main and release_1.0 branches both declared version: '2.0' because the version line was not updated after branching:

The message lists both locations, which is the diagnosis: the two branches in lines 1 and 2 claim the same 2.0@pocket-units. The fix is to give each branch its own version, or to stop selecting one of them.

The version number alone is not the problem: the same version under a different component name is fine, because the pair must match. The rules for choosing versions are in Versioning and prerelease.

Page conversion does not stop for a broken reference. Antora logs the problem, replaces the reference with a visible placeholder, writes the page and continues. A single page containing a missing page xref, a missing module, a missing component, a mistyped version, an unknown attribute, a missing image, a missing include and a missing tag produced:

(The source: lines are omitted from this listing.) The build exited with code 0. In the generated HTML an unresolved xref is an anchor whose href starts with # and whose class is xref unresolved, for example href="#guides:nothing.adoc"; an unresolved include is replaced in the page by an Unresolved include directive line that names the page and the include; and a missing image is an img with the requested file name as src, which gives a broken picture. Searching the output is therefore another way to find problems: grep for xref unresolved and Unresolved include in build/site.

Things the messages do not tell you:

To fail the build on these messages, use --log-failure-level=error as shown above. Includes also depend on the family folder: example$ resolves to modules/<module>/examples, partial$ to modules/<module>/partials. See Partials, examples and attachments.

Source: Antora docs: Page-to-page xrefs

Antora downloads a remote UI bundle once and keeps the ZIP in its cache, keyed by the URL. A later build with the same URL reuses the cached copy, even when the file at the URL has changed. The symptom is a theme or template change that never reaches the site. The reproduction served a bundle from a local HTTP server, republished a changed bundle at the same URL and read the CSS marker that the changed bundle added to _/css/site.css:

Only the combination of snapshot: true and a fetch refreshes the bundle. --fetch alone does not, because a bundle without snapshot is assumed to be immutable: that is correct for a versioned release URL and wrong for a URL such as a "latest" download link or a file on a branch. This site sets snapshot: true for its bundle, but its bundle URL is the local path ui-bundle.zip, which is read on every build, so the key has no effect there.

Source: Antora docs: Specify a UI bundle

Other ways to get a fresh bundle are to change the URL (a version in the file name is the cleanest), to point at a local unzipped directory while developing, or to delete the cached ZIP. The cache location depends on the platform: on Linux it is $XDG_CACHE_HOME/antora or $HOME/.cache/antora, on macOS $HOME/Library/Caches/antora and on Windows $APPDATA/antora/Caches. The scratch build above created a ui folder with the ZIP and a content folder with the cloned repositories inside the cache. --cache-dir, runtime.cache_dir or ANTORA_CACHE_DIR change the location, which is also how to get a clean cache in CI. The cache option and the Docker case are in CLI, Docker, cache and private repositories.

A wrong local bundle path is an explicit error. It stops the build with a message that shows both the resolved and the written path, and a relative path is resolved against the playbook file:

Source: Antora docs: Specify a UI bundle

The same cache idea applies to remote content repositories: Antora clones them into the cache and only updates them with --fetch or runtime.fetch: true, so a branch pushed after the last fetch is not seen until then.

Antora writes the UI files into a folder named _ at the site root. The sample build produced a site root that contained exactly _ and pocket-units, and every page links to its styles through a path such as ../../_/css/site.css. Jekyll, which GitHub Pages runs when a site is published from a branch, ignores files and folders whose names start with an underscore. The published site then loads with no CSS, scripts, fonts or images from _, although the HTML pages are there. Typical symptoms are an unstyled page and 404 responses for _/css/site.css in the browser developer tools.

The cure is a file named .nojekyll at the root of the published folder, or publishing with the actions/deploy-pages flow, which does not run Jekyll. A supplemental file entry alone is not enough: in the reproduction a supplemental_files item with only path: .nojekyll (with or without empty contents) produced no file in the output, and listing it under static_files in ui.yml did. This is the configuration that produced .nojekyll in build/site:

Source: Antora docs: Supplemental UI files

The ui.yml entry replaces the bundle’s own ui.yml, so if the bundle declares other static files, list them too. The listing of the site root after the build was .nojekyll, _ and pocket-units. Jekyll itself was not run in the scratch environment, so the effect on GitHub Pages is described from the official publishing guide and not reproduced here. The complete branch-based publishing flow is in Publishing.

Source: Antora docs: Publish to GitHub Pages