Backstage TechDocs "Unable to read ... mkdocs.yml" in CI

TechDocs reads mkdocs.yml (or mkdocs.yaml) at the source location named by the backstage.io/techdocs-ref annotation. If the file is missing, misnamed, or at the wrong path, generation fails before it starts.

What this error means

TechDocs fails with "Could not read mkdocs YAML config file" or "Unable to read ... mkdocs.yml" for the entity source directory.

backstage

Error: Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml
for validation; caused by Error: ENOENT: no such file or directory,
open '/tmp/techdocs/example-service/mkdocs.yml'

Common causes

No mkdocs.yml at the source location

The techdocs-ref points at a directory or repo that has no mkdocs.yml, so there is nothing to build.

The file is misnamed or in the wrong path

The config is named differently or lives in a subfolder the ref does not point at.

How to fix it

Add mkdocs.yml at the referenced location

Confirm the techdocs-ref annotation points at the directory that has the docs.
Add mkdocs.yml with the techdocs-core plugin at that path.
Re-run generation.

mkdocs.yml

site_name: Example Service
docs_dir: docs
plugins:
  - techdocs-core

Fix the techdocs-ref annotation

Point the annotation at the location that actually holds mkdocs.yml.

catalog-info.yaml

metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

How to prevent it

Keep an mkdocs.yml at every TechDocs source location.
Match techdocs-ref to the directory that holds the config.
Validate TechDocs sources in CI so missing configs fail early.