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

By Kaveh Alemi·Latchkey

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.

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

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

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.

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.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation