## 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
```text
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