---
title: "Debug a spec that will not generate"
description: "From spec_error or a wall of warnings to a clean generation: read the message, find it in the reference, fix it in the spec or with a patch, regenerate."
url: https://typeship.dev/docs/workflows/debug-a-spec
markdown: https://typeship.dev/docs/workflows/debug-a-spec.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# Debug a spec that will not generate

From spec_error or a wall of warnings to a clean generation: read the message, find it in the reference, fix it in the spec or with a patch, regenerate.

## Quick reference

```bash
typeship generate run --spec '{"url":"..."}' --language typescript > /tmp/gen.json 2>/tmp/gen.err
cat /tmp/gen.err                           # SPEC_INVALID envelope when the spec is unusable; the generator's message verbatim
jq '.warnings' /tmp/gen.json               # what was skipped or approximated
typeship docs search "<the message>"       # the entry in Errors and warnings, with the fix
typeship docs read spec-compatibility      # what maps to what
```

## Why these commands

**Two kinds of message.** An error (`spec_error` on the API, `SPEC_INVALID` in the CLI) means the document cannot be used as a spec at all: not YAML or JSON, no paths, an unsupported version. Warnings never block generation; they say what was left out. Every message is listed verbatim with its fix in [Errors and warnings](https://typeship.dev/docs/reference/errors-and-warnings).

**Most fixes are one field.** A relative `servers[0].url` means every user passes `baseUrl`; an `operationId` missing or duplicated means a derived, uglier method name; a security scheme typeship cannot map means no auth option; a `oneOf` without a discriminator means a looser type. [Spec compatibility](https://typeship.dev/docs/reference/spec-compatibility) is the map from spec construct to generated shape.

**Fix at the source, or patch.** Change the spec when you own it. When you do not, a [spec patch](https://typeship.dev/docs/projects/spec-patches) on the project sets, renames, or removes at a JSON Pointer before every generation and survives regeneration. `typeship projects update <id> --spec-patches '[...]'` then `typeship projects generate <id>`, and diff `.warnings`.

**Large specs.** Past 100 operations the MCP server switches to meta tools (search, read, execute) so agents are not flooded; the SDK and CLI are unaffected. Anonymous and free generations stop at 25 operations, which is a cap, not a spec problem.

> **For AI agents:** Quote the generator's message to the user exactly; it is written to be searched. Propose the smallest spec change or patch that clears it, regenerate, and show the warning count before and after. Do not hand-edit generated files to work around a spec problem.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)