doxygen "error: tag file could not be opened" TAGFILES

TL;DR

Check the TAGFILES entry syntax: each entry is tagfile=location. Verify the tag file exists at that path, regenerate it from the upstream Doxygen run if stale or missing, then rebuild.

The exact error

error: tag file could not be opened

Steps

1. Read the TAGFILES entry Open the Doxyfile and find the TAGFILES line. Each entry must be path/to/tag=docs/location with the equals sign separating them. Success check: You can see the malformed or missing entry.

2. Verify the tag file exists Check the filesystem for the tag file at the given path. A moved upstream docs build or a cleaned output directory deletes it. Success check: You know whether the file is missing, stale, or just mispointed.

3. Regenerate from upstream Rebuild the upstream project with GENERATE_TAGFILE set so it emits a fresh tag file, then point TAGFILES at the new artifact. Success check: A fresh, current tag file exists at the configured path.

4. Rebuild and check links Run doxygen and confirm no tag file errors, then verify cross-project links resolve. Success check: Clean run and working links into the upstream documentation.

When to use

• Use when Doxygen cannot open a TAGFILES tag file.
• Use when cross-project Doxygen links break after an upstream rebuild.

When not to use

• Not for 'unable to resolve reference' warnings (the tag file loaded; the symbol is missing).
• Not for undocumented-symbol warnings (different check entirely).

Why it happens

TAGFILES entries pair a tag file path with the base URL of the upstream docs, separated by =. A missing file, a wrong path, or a forgotten = all produce the could-not-be-opened error before any linking is attempted.

Edge cases

Tag files go stale when the upstream API changes; regenerating them is part of the upstream release process, not a one-time setup. CI should fetch or rebuild tag files before the downstream Doxygen run, not rely on checked-in copies.

Provenance

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

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

Thread query: doxygen "error: tag file could not be opened" TAGFILES

TL;DR: Check the TAGFILES entry syntax: each entry is tagfile=location. Verify the tag file exists at that path, regenerate it from the upstream Doxygen run if stale or missing, then rebuild.