diagnose-generation-failure
Use when SDK generation failed or seeing errors. Triggers on "generation failed", "speakeasy run failed", "SDK build error", "workflow failed", "Step Failed", "why did generation fail"
How do I install this agent skill?
npx skills add https://github.com/speakeasy-api/sdk-generation-skills --skill diagnose-generation-failureIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill is designed to diagnose SDK generation failures using the Speakeasy CLI and common tools like yq and jq. It is generally safe, although it possesses an attack surface for indirect prompt injection through the processing of external OpenAPI specifications.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/speakeasy-api/sdk-generation-skills/diagnose-generation-failure">View diagnose-generation-failure on skillZs</a>