RCA-2026-02-24 - Antora Include Path and Tag Mismatches

Executive Summary

Antora documentation builds failed with 50+ errors due to example include paths referencing incorrect file locations and non-existent tags. Root cause was a combination of example file reorganization into subdirectories without updating includes, and documentation pages referencing tags that were never created in example files. Fixed across three repos: domus-infra-ops, domus-netapi-docs, and domus-ise-windows.

Timeline

Time Event

2026-02-24 ~22:00

Build errors observed during routine make in domus-docs

2026-02-24 ~22:05

Investigation started - analyzed error messages

2026-02-24 ~22:15

Root cause identified: path mismatches and missing tags

2026-02-24 ~22:45

Fixes implemented across 3 repos (18 files)

2026-02-24 ~23:00

Verification complete - build succeeds with 0 errors

Problem Statement

Symptoms

  • Antora build failed with 50+ ERROR messages

  • Errors of type: include file not found: /path/to/example$file.adoc

  • Errors of type: tag 'name' not found in include file

  • Errors of type: section title out of sequence

Expected Behavior

make should complete with 0 errors, 0 warnings, producing valid HTML output.

Actual Behavior

[ERROR] asciidoctor: ERROR: runbooks/backup-all-infrastructure.adoc: line 45: include file not found: example$backup-all.sh
[ERROR] asciidoctor: ERROR: runbooks/bind-operations-quick-ref.adoc: line 12: include file not found: example$bind-operations.sh
[WARN] asciidoctor: WARNING: api-reference-v2/pxgrid/services/sessions.adoc: tag 'setup' not found in include file
[WARN] asciidoctor: WARNING: partials/certificate-verification-powershell.adoc: line 3: section title out of sequence

Root Cause

5 Whys Analysis

Why # Question and Answer

1

Why did include errors occur?
Because: Include paths didn’t match actual file locations

2

Why didn’t paths match file locations?
Because: Example files were reorganized into subdirectories (backup/, dns/, vault/)

3

Why weren’t includes updated when files moved?
Because: No automated validation of include paths exists

4

Why did tag errors occur?
Because: Pages referenced tags that didn’t exist in example files

5

Why were non-existent tags referenced?
Because: No pre-commit check validates tags exist before referencing them

Pattern 4: Missing AsciiDoc Attributes

Problem: Pages referenced attributes that weren’t defined in antora.yml.

[WARN] asciidoctor: skipping reference to missing attribute: ise-pan-ip
[WARN] asciidoctor: skipping reference to missing attribute: ise-host
[WARN] asciidoctor: skipping reference to missing attribute: service

Fix approach:

  1. Check antora.yml for defined attributes

  2. Add missing attributes with appropriate values

  3. For generic placeholders, use descriptive values (e.g., id: <resource-id>)

Affected repos:

  • domus-ise-linux: Added ise-pan-ip, ise-psn-ip

  • domus-netapi-docs: Added ise-host, ise-mnt, ise_api_user, id, service, mac, etc.

Root Cause Statement

Documentation pages referenced example files using outdated flat paths (e.g., example$backup-all.sh) after example files were reorganized into categorized subdirectories (e.g., example$backup/backup-all.sh). Additionally, pages referenced tags that were never defined in the example files, and AsciiDoc attributes that weren’t defined in antora.yml.

Contributing Factors

Factor Description Preventable?

No path validation

Antora only validates at build time, not at write time

Partially (could add pre-commit hook)

No tag registry

No inventory of available tags in example files

Yes (could document available tags)

Template drift

Templates assumed tags that were never implemented

Yes (review templates against reality)

Section level assumptions

Partials assumed certain leveloffset without documenting requirement

Yes (document expected leveloffset)

Missing attributes

Pages used attributes not defined in antora.yml

Yes (audit attributes before using)

Impact

Severity

Metric Value

Severity

P2 - Documentation broken but infrastructure unaffected

Duration

~1 hour from detection to fix

Users/Systems Affected

Documentation consumers (developers, ops)

Data Loss

None

Business Impact

  • Documentation site not deployable until fixed

  • No revenue or security impact

  • Productivity impact: blocks documentation updates

Resolution

Immediate Actions (What was done)

domus-infra-ops (12 files)

  1. Fixed backup script includes: example$backup-.sh → example$backup/backup-.sh

  2. Fixed BIND includes: example$bind-operations.sh → example$dns/bind-operations.sh

  3. Fixed Vault SSH includes: example$vault-ssh- → example$vault/vault-ssh-

  4. Fixed broken xrefs: dr-shahab-linux-workstation.adoc → linux-research-workstation.adoc

domus-netapi-docs (5 files)

  1. Rewrote dataconnect/queries.adoc to use existing tags

  2. Rewrote pxgrid/services/sessions.adoc to use existing tags

  3. Rewrote mnt/sessions.adoc to use existing tags

  4. Rewrote ers/network-devices/index.adoc to use existing tags

  5. Removed broken xrefs from ers/endpoints/index.adoc

domus-ise-windows (1 file)

  1. Fixed partials/certificate-verification-powershell.adoc section levels (=== → ==)

domus-ise-linux (antora.yml)

  1. Added ise-pan-ip: 10.50.1.20 (Primary Admin Node alias)

  2. Added ise-psn-ip: 10.50.1.20 (Policy Service Node alias)

domus-netapi-docs (antora.yml)

  1. Added ISE attributes: ise-host, ise-mnt, ise-pan-ip, ise-psn-ip

  2. Added API credentials: ise_api_user, ise_api_pass, ise_api_token

  3. Added generic placeholders: id, service, mac, ip, name

Verification

cd /home/evanusmodestus/atelier/_bibliotheca/domus-docs
make 2>&1 | grep -E "(ERROR|WARN)" | wc -l
# Output: 0

Preventive Measures

Short-term (This week)

Action Owner Status

Add pre-commit grep for missing example files

evanusmodestus

[ ] Pending

Document available tags in each example file header

evanusmodestus

[ ] Pending

Add leveloffset requirement to partial template

evanusmodestus

[ ] Pending

Long-term (This quarter)

Action Owner Status

Create make validate-includes target

evanusmodestus

[ ] Pending

Add CI check for include/tag validity

evanusmodestus

[ ] Pending

Create examples/ directory README documenting structure

evanusmodestus

[ ] Pending

Detection

How was it detected?

  • Manual observation during routine make build

Detection Gap

Could have been detected earlier with:

  • Pre-commit hook checking include paths exist

  • CI job running make on every push

Lessons Learned

What went well

  • Root cause was quickly identified from error messages

  • Fixes were systematic - pattern-based rather than one-off

  • Used grep/awk to find all affected files at once

What could be improved

  • Should have updated includes when reorganizing example files

  • Should validate tags exist before referencing them

  • Need better documentation of example file structure

Key Takeaways

  1. Always run make before committing documentation changes - catches includes/tags/attributes errors

  2. When reorganizing example files, update ALL includes in same commit - atomic changes

  3. Check tags exist in example file before referencing - grep "tag::name" /path/to/example

  4. Partials should document their expected leveloffset - in header comment

  5. Check antora.yml before using attributes - grep "attr-name" antora.yml

Detection Commands for Future Reference

Find Available Tags in Example File

grep -n "tag::" /path/to/examples/file.adoc

Find All Example Includes in a Repo

grep -rn "include::example" /path/to/repo/docs

Verify Example File Exists

# Check if include target exists
ls -la /path/to/repo/docs/asciidoc/modules/ROOT/examples/backup/backup-all.sh

List All Example Files

find /path/to/repo/docs -path "*examples*" -type f | sort

Find Missing Attributes

# Run build and filter for missing attributes
make 2>&1 | grep "missing attribute" | grep -oP "attribute: \K[^ ]+" | sort -u

# Check if attribute exists in antora.yml
grep "ise-pan-ip" /path/to/repo/docs/asciidoc/antora.yml

Related

Metadata

Field Value

RCA ID

RCA-2026-02-24-001

Author

evanusmodestus

Date Created

2026-02-24

Last Updated

2026-02-24

Status

Final

Review Date

2026-03-24