Debug a spec that will not generate

Quick reference

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.

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 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 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.