verbose: Error: Config file 'mkdocs.yml' does not exist. despite in correct workspace which has mkdocs.yml, catalog-info.yaml

[monajalal]

So we have created an Azure Container (ACR) using the base techdocs container, that we pull and pass to techdocs-cli command, however, we keep getting the error mkdocs.yml not found despite running it inside the code repo (we call it bazel_project) which has mkdocs.yml, catalog-info-yaml and a documentation folder (which we have specifically mentioned is our doc folder) (aka in mkdocs.yml we have docs_dir: documentation ). Please note techdocs_acr is hosted on our own Azure privately.

Please note the following command is being run in REPO_PATH (already) and we are also specifying it via source-dir. Further, our output-dir is a separate folder.

I installed techdocs-cli via the following inside Azure Pipeline:

  - task: UseNode@1
    displayName: "Use Node.js 22.18.0"
    inputs:
      version: '22.18.0'

npm install -g @techdocs/cli@1.9.7

This is the command I am stuck at:

      docker pull techdocs_acr:latest
      techdocs-cli generate \
          --source-dir "${REPO_PATH}" \
          --output-dir "${SITE_DIR}" \
          --docker-image techdocs_acr:latest \
          --verbose --no-pull 

2025-09-17T15:53:59.9028767Z techdocs-cli version: 1.9.7
2025-09-17T15:53:59.9033017Z current dir: /azp/_work/1/s/bazel_project
2025-09-17T15:53:59.9033591Z REPO_PATH: /azp/_work/1/s/bazel_project
2025-09-17T15:53:59.9046276Z total 84
2025-09-17T15:53:59.9046634Z drwxr-xr-x 5 agent agent  4096 Sep 17 15:53 .
2025-09-17T15:53:59.9046973Z drwxr-xr-x 5 agent agent  4096 Sep 17 15:53 ..
2025-09-17T15:53:59.9047229Z drwxr-xr-x 8 agent agent  4096 Sep 17 15:53 .git
2025-09-17T15:53:59.9047513Z -rw-r--r-- 1 agent agent  1070 Sep 16 18:36 .gitignore
2025-09-17T15:53:59.9049455Z -rw-r--r-- 1 agent agent   892 Sep 16 18:36 catalog-info.yaml
2025-09-17T15:53:59.9050017Z drwxr-xr-x 8 agent agent  4096 Sep 16 18:36 documentation
2025-09-17T15:53:59.9050177Z -rw-r--r-- 1 agent agent  1697 Sep 17 15:53 mkdocs.yml


2025-09-17T15:54:00.8546179Z info: Using source dir /azp/_work/1/s/bazel_project
2025-09-17T15:54:00.8551411Z info: Will output generated files in /azp/_work/1/s/techdocs_site/
2025-09-17T15:54:00.8552000Z verbose: Creating output directory if it does not exist.
2025-09-17T15:54:00.8596723Z info: Generating documentation...
2025-09-17T15:54:01.2787562Z verbose: Error: Config file 'mkdocs.yml' does not exist.

Please note, when I also tried the same workflow with spotify techdocs docker, still get the same exact error, here is the only different part in code:

docker pull spotify/techdocs:latest
techdocs-cli generate \
    --source-dir "${REPO_PATH}" \
    --output-dir "${SITE_DIR}" \
    --docker-image spotify/techdocs:latest \
    --verbose --no-pull 

Also:

REPO_PATH="$(Build.SourcesDirectory)/bazel_project"

Further, please note, when I run the same locally, it works out of the box with my techdocs-acr and techdocs-cli 1.9.7

[awanlin]

Hi @monajalal, sorry to do this but I think this would be better to be submitted in the main Backstage repo as this plugin would only come into the equation once the mkdocs.yml is being used which in this case is not. I would move the issue but I don't have the permissions, you can probably copy most of what you have here into this: https://github.com/backstage/backstage/issues/new?template=01_bug.yaml

[awanlin]

Hi @monajalal, did you get a chance to log this in the Backstage repo? I haven't seen it but I may simply have missed it.