Universal Documentation Engine Operational Documentation

Appearance

Troubleshooting Operational Failures ​

This enterprise-grade operational reference guide outlines 7 typical scenarios, diagnosing UDE v2.0 pipeline anomalies with concrete, step-by-step remediation procedures.

1. Missing or Malformed src_dir ​

Symptom: The pipeline fails immediately with Error: 'src_dir' must be a list of paths. String values are not accepted — wrap single paths in a JSON array. or Error: No source directory specified.Root Cause: The target's ude_doc_config.json either omits src_dir entirely, or sets it to a bare string instead of a JSON array (a real engine constraint — enforced in UdeOrchestrator.parse() and again in DoxygenXmlCollector.validate_environment(), which raises a CollectorError with a similar message if the collector-level config still has a bad value). Remediation:

  1. Open the target's ude_doc_config.json.
  2. Confirm src_dir is a JSON array, even for a single path: "src_dir": ["./src"], not "src_dir": "./src".
  3. Confirm each path is relative to the ude_doc_config.json file's own directory (paths are resolved relative to the config file, not the CWD or repo root).
  4. Re-run ude parse or ude compile.

2. Pydantic Type Validation Mismatches (Legacy v1.0 Catalogs) ​

Symptom: ValidationError: fields.0: value is not a valid dict during IR loading. Root Cause: A stale v1.0 Intermediate Representation (IR) containing strings (e.g., ["int x"]) is being parsed by v2.0 ClassEntity Pydantic models. Remediation:

  1. Do not reuse a legacy v1.0 IR file (from ude parse --output-ir ...) with a v2.0 ude render.
  2. Delete the stale IR file and any .build_cache.json.gz in the output directory.
  3. Regenerate a fresh IR from source: ude parse --doc-config ude_doc_config.json --output-ir catalog_ir.gz, then render from it, or simply run ude compile --doc-config ude_doc_config.json to redo both stages in one step.

3. L2 Render Cache Invalidated by Output Directory Wipes ​

Symptom: Compilation time increases noticeably on what should be an incremental build. Root Cause: A preemptive build step is deleting the L2 render cache (a .build_cache.json.gz file written into the output directory by default) before UDE runs. Remediation:

  1. Check CI configurations for aggressive clean steps (e.g., git clean -fdx) that remove the output directory between runs.
  2. If you need the cache to live outside the output directory, set cache_root_dir explicitly in your global or target config JSON (GlobalConfig.cache_root_dir, resolved to an absolute path relative to the config file's own directory) and persist that directory across CI runs via actions/cache.
  3. Note: there is no --cache-dir (or --no-cache/--all) CLI flag — cache location is controlled exclusively via the cache_root_dir JSON config key, not a command-line option.

4. Missing VitePress Trailing Comma Linter Blocks ​

Symptom: user-docs deployment fails on npm run build with trailing comma syntax errors. Root Cause: Strict Prettier/ESLint configs in VitePress reject Python-generated MD arrays if trailing commas are missing. Remediation:

  1. Modify your custom renderer templates in engine/ude/renderers/.
  2. Ensure JSON/JS blocks within markdown generate trailing commas in multi-line structures.
  3. Run npm run lint:fix locally inside user-docs/.

5. Cloudflare Pages Deploy Fails with "Project not found" (code 8000007) ​

Symptom: Deploy to Cloudflare Pages step fails: A request to the Cloudflare API (/accounts/***/pages/projects/<name>) failed. Project not found.Root Cause: wrangler pages deploy (used by every deploy.yml in this ecosystem) does not create the Cloudflare Pages project automatically on first use — only the deployment, once the named project already exists. Hit live 2026-07-22 on ude_promotion's first deploy. Remediation:

  1. Create the project once via the Cloudflare dashboard, or wrangler pages project create <name> --production-branch=<branch>.
  2. Set --production-branch explicitly if the repo's default branch isn't Cloudflare's own default (main) — otherwise deploys to e.g. master land as invisible "Preview" deployments instead of updating the project's real *.pages.dev domain.
  3. Re-run the deploy (workflow_dispatch or push again).

6. A Deployed Site Returns a Cloudflare Access Login Redirect Instead of Real Content ​

Symptom: curl/browser hits https://<project>.pages.dev/ and gets redirected to a cloudflareaccess.com login page rather than the actual site. Root Cause: That Cloudflare Pages project has Cloudflare Access (Zero Trust) enabled at the project level — this is dashboard/API configuration, not something any deploy.yml in this ecosystem sets. Easy to misread as "the deploy is broken" when the deploy actually succeeded; the content is just gated. Remediation:

  1. Check that project's Access policy in the Cloudflare Zero Trust dashboard, not the deploy workflow logs.
  2. To verify deploy correctness without going through Access, check the workflow's own build/lint steps passed, or rebuild locally with the same environment variables the workflow uses and inspect the output directly.

7. AST Traceability Annotation Failures ​

Symptom: Output documentation lacks source code line trace links (github.com/org/repo/blob/main/file.cpp#L12). Root Cause: Doxygen failed to generate XML source linkage annotations. Remediation:

  1. Edit Doxyfile.
  2. Set SOURCE_BROWSER = YES and GENERATE_XML = YES.
  3. Re-run ude parse.

(Paths below are repository-root-relative.)

  • user-docs/docs/admin-deployment.md — deployment architecture referenced in scenarios 5 and 6
  • .github/AGENTS.md — per-workflow catalog for the CI jobs these scenarios occur in
  • RUNBOOK.md §3 — PAT rotation procedure referenced in scenario 6

Copyright © 2026