Terminal
Terminal/Skill
Finds the root cause when Speakeasy SDK generation fails and decides whether an overlay, a spec fix, or your input is needed.
By Speakeasy
Works with
npx skills add speakeasy-api/sdk-generation-skills --skill diagnose-generation-failureWhen SDK generation fails, diagnose the root cause and determine the fix strategy.
speakeasy run failed with errors| Input | Required | Description |
|---|---|---|
| OpenAPI spec | Yes | Path to spec that failed generation |
| Error output | Helpful | Error messages from failed run |
| Output | Description |
|---|---|
| Diagnosis | Root cause of failure |
| Fix strategy | Overlay vs spec fix vs user decision |
| Action items | Specific steps to resolve |
Run lint to get detailed errors:
speakeasy lint openapi --non-interactive -s <spec-path>
Categorize issues:
| 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 |
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
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
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]
manage-openapi-overlays - Fix issues with overlayssetup-sdk-testing - Contract testing for validationwriting-openapi-specs - Spec design best practices