-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Almost always one of two things:
1. The config file wasn't found. A missing doc-gen.config.yml does not fail the run — it logs a warning and proceeds on defaults, reading ./unpacked with an empty publisher prefix. Check the log for No doc-gen.config.yml found, and confirm DOC_GEN_CONFIG_DIR points at the folder containing the file (and that the filename is exactly doc-gen.config.yml).
2. The publisher prefix is wrong or missing. Custom-component detection drives the ER diagram, security roles, global choices and model-driven apps. A wrong prefix means nothing matches. See Solutions.
The folder in solutions[].path must contain Other/Solution.xml. Two common causes: pointing at the parent of the unpacked folder rather than the folder itself, or a path that's relative to the config file rather than to the working directory. solutions[].path resolves from where the command runs, not from the config file's folder.
PowerAutoDocs renders Mermaid diagrams to PNG using a Chrome-family browser, and deliberately does not download its own Chromium — on an ADO agent that download would be paid on every single run.
When no browser is found, the run logs a warning, produces the .docx without diagrams, and exits cleanly. A green run with a diagram-free document is the symptom.
It looks for, in order:
-
POWERAUTODOCS_CHROME_PATH, if set — throws if that path doesn't exist, so an explicit override is never silently ignored - Common install locations for Chrome, Chromium and Edge on macOS, Linux and Windows
Fixes:
- Install Chrome or Edge on the machine, or
- Set
POWERAUTODOCS_CHROME_PATHto the executable
Do not run npx puppeteer browsers install chrome — that reimposes the ~250MB per-run download the setup exists to avoid.
The diagram cache is keyed only on the Mermaid source text. Changes to render settings don't invalidate it. Delete <cache.dir>/diagrams/ and re-run. See Caching.
| Symptom | Cause |
|---|---|
| "skipping publish" warning |
--wiki passed but no wiki block in the config |
| PAT rejected / publish failure | The REDACTED placeholder was never replaced. PowerAutoDocs refuses to publish with an empty or literal-REDACTED PAT. Check step 2 of the pipeline ran, and that WIKI_PAT exists as a secret pipeline variable. |
| 401 / 403 from ADO | The PAT lacks Wiki (Read & Write) scope, or has expired |
| Pages appear in the wrong place | Check wiki.parentPath
|
Validation is fail-fast and lists every problem at once. Usual causes: the provider block doesn't match the provider value, a required Azure field (deployment, apiVersion, endpointEnv) is missing, or enabled: true with no component opted in — all AI component toggles default to false.
ADO does not expose secret pipeline variables to script steps automatically. They must be mapped through an explicit env: block on the step. The sample pipeline does this in step 3.
The cache isn't persisting. Agents are ephemeral, so the commit-back step (step 4) is what carries the cache between runs — and it needs the ADO Build Service account to have Contribute on the repo. See Caching.
The cache commit-back step (step 4) cannot push. GenericContribute is what the Contribute permission is called on the wire, so this is the permission error above wearing a different name — the commit succeeds locally and only the git push is rejected, with a 403.
Fix it at Project Settings → Repos → your repo → Security → select "<Project> Build Service (<Org>)" → set Contribute to Allow. Grant only that: the step does a plain fast-forward push, so Force push, Bypass policies and Delete or disable repository should stay unset.
Beware the display: inheritance being On does not mean Contribute is granted. Check that specific row reads Allow — neighbouring rows may show Allow (inherited) while Contribute reads Not set.
Your documentation is unaffected — the wiki publish and Word build both complete before this step runs. Only caching is lost, so the next run re-pays for every AI summary and re-renders every diagram.
components.environmentVariables.showCurrentValue defaults to true, and current values are runtime values. Set it to false. See Component Toggles.
Only ---prefixed tokens are validated. -word or an em-dashed —word (common from copy-paste out of a document) are silently ignored and the run falls through to your config. Retype the flag with two plain hyphens.
Arrays are replaced on merge, not concatenated. To add one exclusion you must list all 12 defaults plus yours. See Parse & Render Options.