RCA-2026-02-26: Missing Antora Attributes
Executive Summary
Documentation build produced 6 "skipping reference to missing attribute" warnings. Root cause: Document written using assumed attribute names without first verifying they exist in antora.yml.
Timeline
| Time | Event |
|---|---|
2026-02-26 18:58 |
User runs |
2026-02-26 18:59 |
User reports: "we keep on overlooking this" |
2026-02-26 19:05 |
Fix: 5 attribute aliases added to antora.yml |
2026-02-26 19:12 |
Build verified clean |
Problem
Build output:
[WARN] skipping reference to missing attribute: wazuh-manager-vip [WARN] skipping reference to missing attribute: kvm-01-ip [WARN] skipping reference to missing attribute: ipa-01-ip [WARN] skipping reference to missing attribute: keycloak-01-ip [WARN] skipping reference to missing attribute: ad-dc-ip
Root Cause Analysis
5 Whys
| Why # | Answer |
|---|---|
1 |
Why warnings? Document used |
2 |
Why wrong name? Assumed |
3 |
Why wrong assumption? Existing attributes inconsistent (some have suffix, some don’t) |
4 |
Why wasn’t antora.yml checked? Time pressure |
5 |
Why no build before commit? No enforced pre-commit hook |
|
Root Cause: Violated mandatory attribute verification rule by writing AsciiDoc with assumed attribute names without first running |
Resolution
Added Attribute Aliases
# antora.yml additions
wazuh-manager-vip: 10.50.1.134 # Alias for wazuh-api-vip
ad-dc-ip: 10.50.1.50 # Alias for homedc-ip
keycloak-01-ip: 10.50.1.80 # Alias for keycloak-ip
ipa-01-ip: 10.50.1.100 # Alias for ipa-ip
kvm-01-ip: 10.50.1.99 # Alias for kvm-ip
CLI Mastery: Attribute Verification
Before Writing: Verify Attribute Exists
# Search for attribute pattern
grep -i "kvm" docs/asciidoc/antora.yml
# List all IP attributes
grep -E "^\s+\w+-ip:" docs/asciidoc/antora.yml | awk -F: '{print $1}' | sort
After Writing: Find Undefined Attributes
make 2>&1 | grep "missing attribute" | awk -F': ' '{print $NF}' | sort -u
Bulk Attribute Audit
# Check all attributes in document against antora.yml
grep -oE '\{[a-z0-9-]+\}' document.adoc | \
tr -d '{}' | sort -u | while read attr; do
grep -q "^\s*${attr}:" docs/asciidoc/antora.yml && \
echo "✓ $attr" || echo "✗ $attr MISSING"
done
Prevention
Mandatory Pre-Write Checklist
-
grep antora.ymlfor attribute before using it -
If attribute doesn’t exist, add it first
-
Run
makebefore committing -
Check for 0 warnings
Shell Function
# Add to .bashrc/.zshrc
attr-check() {
local attr="$1"
grep -q "^\s*${attr}:" docs/asciidoc/antora.yml && \
echo "✓ $attr exists" || echo "✗ $attr MISSING - add to antora.yml"
}
Key Lessons
| Issue | Prevention |
|---|---|
Assumed attribute names |
Always |
No build verification |
Run |
Inconsistent naming |
Use aliases for both patterns (with/without |
Time pressure |
Discipline over speed - 5 seconds prevents 15 minutes |
Metadata
| Field | Value |
|---|---|
RCA ID |
RCA-2026-02-26-001 |
Author |
Evan Rosado |
Date |
2026-02-26 |
Status |
Final |
Category |
Documentation / Build |