Debug an API contract 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
typeship generate run --definition '{"url":"..."}' --target typescript-sdk > /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 whatWhy 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 Definition when you own it. When you do not, a Definition patch sets, renames, or removes at a JSON Pointer before every Generation. Run typeship definitions update <definition_id> --patches '[...]', then typeship projects generate <project_id>, and diff .warnings.
Large tool surfaces. In auto mode, the MCP server switches to meta tools (search, read, execute) when per-operation discovery approaches 10k tokens or the spec passes 100 operations. This accounts for detailed schemas, not just endpoint count; the SDK and CLI are unaffected. Anonymous and free generations stop at 25 operations, which is a cap, not a spec problem.