Troubleshooting Generation Failures & Degradation
When automated generation jobs fail in CI or local CLI execution, use this guide to identify the root cause and apply appropriate fixes.
Common Failure Scenarios
1. PrivacyRoutingError: Local Provider Disabled
- Symptom: CLI exits with
PrivacyRoutingError: Task is privacy: private but local provider is disabled... - Cause: The task is flagged
privacy: private, butai.config.yamlhasproviders.local.enabled: false. - Remediation:
- For offline local testing, start a local OpenAI-compatible endpoint (e.g.
ollama run llama3) and setproviders.local.enabled: trueinai.config.yaml. - In demo mode, use the deterministic
fixtureprovider. - Do NOT change task privacy to
publicmerely to force execution through cloud APIs.
- For offline local testing, start a local OpenAI-compatible endpoint (e.g.
2. Schema Validation Errors on Model Output
- Symptom:
ContractViolation: Output invalid after one repair retry: missing required 'audience' - Cause: The model emitted malformed frontmatter or omitted a mandatory field.
- Remediation:
- The pipeline automatically performs one repair retry appending the validator error trace.
- If it fails repeatedly, verify that the prompt template in
prompts/explicitly demonstrates the required YAML frontmatter structure.
3. Missing Canonical Evidence
- Symptom:
ContractViolation: No canonical page with id '<id>' under docs/source/ - Cause: The requested target ID does not exist or was renamed without updating task references.
- Remediation: Check
prototype/docs/source/for the correct documentidand update your generation command arguments.
4. Broken Link Gate (onBrokenLinks: throw)
- Symptom:
docusaurus buildfails withDocusaurus found broken links. - Cause: A markdown document references an invalid relative path or missing doc ID.
- Remediation: Correct the relative path or ensure explicit
slug:frontmatter is set for the target page.