doxygen "unable to resolve reference to" class error

TL;DR: Point the ref command at the exact documented name. "unable to resolve reference to" means the ref names something doxygen never documented - a typo, a missing namespace qualifier, or a target excluded from the build. Use the fully qualified name, confirm the target page exists in the output, and fall back to plain text when the target is intentionally undocumented.

warning: unable to resolve reference to 'ConfigParser' for ref command

1. Find every broken reference:

   doxygen Doxyfile 2>&1 | grep "unable to resolve reference"

Expected: one line per broken ref, naming the target doxygen could not find.

1. Check whether the target is documented at all: search the generated HTML output for the symbol name. If nothing matches, the target was never documented.
2. Fix the ref to the fully qualified name, for example docs::ConfigParser instead of the bare ConfigParser.
3. Re-run:

   doxygen Doxyfile

Expected: the warnings are gone, and the link in the HTML output points at the target's page.

1. If the target lives in excluded code (an EXCLUDE pattern or an undocumented file), replace the ref with plain text - linking at an undocumented target will never resolve.

Use this when

• doxygen warns "unable to resolve reference to" for a ref command
• A cross-reference in the docs renders as dead text
• You renamed or moved a class and the old references broke

Not for this skill when

• The warning is "documented symbol was not declared or defined" - that is a stale comment block, a different fix
• The target should be documented but is not - fix the target's own documentation first
• Automatic linking already handles the name - plain words that match documented symbols link without an explicit ref

Variant phrasings

• "doxygen unable to resolve reference"
• "doxygen ref command unresolved"
• "warning: unable to resolve reference to"

Why it happens

A ref is an explicit link: doxygen looks up the exact name you give it in the documented symbol table. A typo, a missing namespace qualifier, or a target that was never documented (or was excluded) leaves the lookup with nothing to point at.

Edge cases

• Overloaded names can resolve to the wrong overload; qualify with the class or namespace to disambiguate.
• Members of undocumented classes cannot be reference targets even if the member itself has a comment.
• Case matters: ConfigParser and configParser are different targets.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstxGlyufiyUZ_QeB2saSp7A