diagnose-generation-failure
0
总安装量
9
周安装量
安装命令
npx skills add https://github.com/speakeasy-api/skills --skill diagnose-generation-failure
Agent 安装分布
claude-code
7
codex
7
opencode
7
github-copilot
6
kimi-cli
5
Skill 文档
diagnose-generation-failure
When SDK generation fails, diagnose the root cause and determine the fix strategy.
When to Use
speakeasy runfailed with errors- SDK generation produced unexpected results
- User says: “generation failed”, “SDK build error”, “why did generation fail”
Inputs
| Input | Required | Description |
|---|---|---|
| OpenAPI spec | Yes | Path to spec that failed generation |
| Error output | Helpful | Error messages from failed run |
Outputs
| Output | Description |
|---|---|
| Diagnosis | Root cause of failure |
| Fix strategy | Overlay vs spec fix vs user decision |
| Action items | Specific steps to resolve |
Diagnosis Steps
-
Run lint to get detailed errors:
speakeasy lint openapi --non-interactive -s <spec-path> -
Categorize issues:
- Fixable with overlays: Missing descriptions, poor operation IDs
- Requires spec fix: Invalid schema, missing required fields
- Requires user input: Design decisions, authentication setup
Decision Framework
| Issue Type | Fix Strategy | Example |
|---|---|---|
| Missing operationId | Overlay | Use speakeasy suggest operation-ids |
| Missing description | Overlay | Add via overlay |
| Invalid $ref | Ask user | Broken reference needs spec fix |
| Circular reference | Ask user | Design decision needed |
| Missing security | Ask user | Auth design needed |
What NOT to Do
- Do NOT disable lint rules to hide errors
- Do NOT try to fix every issue one-by-one
- Do NOT modify source spec without asking
- Do NOT assume you can fix structural problems
Troubleshooting Tree
PROBLEM
â
ââ ResponseValidationError at runtime?
â ââ SDK types don't match server responses
â ââ Run contract tests to identify mismatches
â ââ Fix spec or create overlay to correct types
â
ââ SDK doesn't match live API behavior?
â ââ Spec may have drifted from API
â â â Run contract tests to detect drift
â ââ Third-party spec may be inaccurate
â â Validate with contract testing before trusting
â
ââ Type mismatch errors in generated SDK?
â ââ At compile time â Check spec schema definitions
â ââ At runtime â Server returns unexpected types
â â Contract testing required
â
ââ Enum value not recognized?
ââ API returned value not in spec enum
ââ Add missing value to spec/overlay
ââ Or use open enums for anti-fragility
Working with Large OpenAPI Specs
Use yq (YAML) or jq (JSON) to inspect specs without loading full content:
# List all paths
yq '.paths | keys' spec.yaml
# Inspect a specific endpoint
yq '.paths["/users/{id}"]' spec.yaml
# List all schema names
yq '.components.schemas | keys' spec.yaml
# List all operationIds
yq '[.paths[][].operationId // empty] | unique' spec.yaml
Strategy Document
For complex issues, produce a document:
## OpenAPI Spec Analysis
### Blocking Issues (require user input)
- [List issues that need human decision]
### Fixable Issues (can use overlays)
- [List issues with proposed overlay fixes]
### Recommended Approach
[Your recommendation]
Related Skills
manage-openapi-overlays– Fix issues with overlayssetup-sdk-testing– Contract testing for validationwriting-openapi-specs– Spec design best practices