Troubleshooting Operational Failures

This enterprise-grade operational reference guide outlines 9 typical scenarios, diagnosing Flude 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 Flude 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.

8. Diagnosing via Logs and On-Disk Cache Files

Beyond the specific scenarios above, two categories of on-disk state are worth inspecting directly when a build behaves unexpectedly.

Logs. logging_setup(cfg: GlobalConfig) (engine/ude/config.py:219) configures a single ude root logger. Output always goes to stderr; if GlobalConfig.log_file is set, it is also written there (see Global Settings). Console and file output use different formats (_UDE_FORMATTER vs. _UDE_FILE_FORMATTER, engine/ude/config.py:21-22) — the file format additionally prefixes each line with a timestamp, which matters when correlating a build's log file against an external CI timeline.

Cache files, all written under the resolved cache_root_dir (or the output directory, if cache_root_dir is unset — see Troubleshooting §3 above):

File	Purpose
.ude_fingerprint.json	Per-document Collector-stage fingerprint, checked by DoxygenXmlCollector to decide whether Doxygen needs to re-run at all (engine/ude/doxygen_cache.py).
.ude_hash_cache.json	HashSideCache's own sidecar (engine/ude/collectors/doxygen.py:432) — speeds up re-hashing source files across runs; safe to delete, it only costs a slower next hash pass.
.build_cache.json.gz	The L2 render cache (engine/ude/storage.py:184) — skips re-rendering entities whose IR hasn't changed.

If a build behaves as though a source change was never picked up, and re-running with a clean cache_root_dir fixes it, the fingerprint or hash cache is the first place to look — deleting either is always safe and only costs a slower next run, never incorrect output.

9. Proprietary SDK Types Left Unresolved (Windows SDK / Apple Frameworks)

Symptom: A C++ target whose public API directly references a proprietary SDK type — e.g. HWND from <windows.h>, or NSString*/NSArray* from Apple's Foundation/CoreFoundation/AppKit — parses with a parse-fidelity-degraded finding logged for the affected file (libclang encountered missing include paths or macros while parsing '<file>': ...), instead of the real type resolving cleanly.

Root Cause: Windows SDK headers and closed Apple framework headers (Foundation/CoreFoundation/ AppKit — not Darwin/Libc itself, which this pipeline does bundle for macOS targets) cannot legally be redistributed by this pipeline: the Windows SDK's own REDIST.TXT + EULA, and Apple's Xcode and Apple SDKs Agreement, both prohibit it for a commercial SaaS use case like this one. Without the real headers, the native C++ parser genuinely cannot resolve the type — and by design, that surfaces as a diagnosed Finding (rule_id="parse-fidelity-degraded", level="warning"), not silent data corruption (a type silently degrading to int, or a base class silently disappearing with zero diagnostic).

Remediation:

1. You already hold your own license for Visual Studio/Windows SDK or Xcode — this pipeline does not redistribute those headers on your behalf, and legally cannot.
2. Commit the specific headers your public API actually references into your own repository (only what you need, not the whole SDK).
3. Point the existing collector.include_paths config key (see Target Settings) at that directory in your ude_doc_config.json. There is no separate SDK-upload mechanism — include_paths already covers this case.
4. Re-run ude parse / ude compile.

NOTE

parse-fidelity-degraded findings are always visible in the application log, and are recorded in the parsed catalog's metadata.parse_fidelity_findings (inspectable if you dump an intermediate representation via --output-ir, see scenario 2 above) — as of this writing they are not yet wired into the --report-format sarif/codeclimate CLI output. Set collector.on_parse_error to "fail" (default: "warn") if a degraded parse should stop the build immediately rather than only logging a warning.

Related Docs

(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
• user-docs/docs/global-settings.md — log_level/log_file/cache_root_dir field reference
• user-docs/docs/target-settings.md — collector.include_paths field reference, scenario 9