# 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

- **Type:** Skill
- **Install:** `agentstack add skill-speakeasy-api-skills-diagnose-generation-failure`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [speakeasy-api](https://agentstack.voostack.com/s/speakeasy-api)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [speakeasy-api](https://github.com/speakeasy-api)
- **Source:** https://github.com/speakeasy-api/skills/tree/master/skills/diagnose-generation-failure
- **Website:** https://www.speakeasy.com/docs

## Install

```sh
agentstack add skill-speakeasy-api-skills-diagnose-generation-failure
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# diagnose-generation-failure

When SDK generation fails, diagnose the root cause and determine the fix strategy.

## When to Use

- `speakeasy run` failed 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

1. **Run lint to get detailed errors:**
   ```bash
   speakeasy lint openapi --non-interactive -s 
   ```

2. **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:

```bash
# 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:

```markdown
## 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 overlays
- `setup-sdk-testing` - Contract testing for validation
- `writing-openapi-specs` - Spec design best practices

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [speakeasy-api](https://github.com/speakeasy-api)
- **Source:** [speakeasy-api/skills](https://github.com/speakeasy-api/skills)
- **License:** Apache-2.0
- **Homepage:** https://www.speakeasy.com/docs

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-speakeasy-api-skills-diagnose-generation-failure
- Seller: https://agentstack.voostack.com/s/speakeasy-api
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.