Fix a spec that will not generate

Find the source of a generation error or warning, correct the spec, and verify the next result.

Start with the error message from the failed Generation. An error such as API spec_invalid or CLI SPEC_INVALID means the document cannot be used. Warnings describe unsupported or approximated behavior in a generated package and do not block generation by themselves.

You need the installed Typeship CLI, jq, and access to the spec or permission to update its Project's patches. Fix the source when possible so every consumer benefits from the correction.

Inspect a generation

Open the Generation's error or warnings. For a one-shot terminal run, replace <specification-url> and capture both outputs:
```
if typeship packages generate --spec '{"url":"<specification-url>"}' \
  --target '{"type":"typescript_sdk"}' > generation.json 2> generation-stderr.txt; then
  jq '{warnings, coverage}' generation.json
else
  cat generation-stderr.txt
fi
```
A nonzero exit means the command failed. On success, inspect warnings in stdout. An anonymous run may print an unclaimed-project notice on stderr even when generation succeeds; stderr output alone is not a failure signal.
Find the message in Errors and warnings, or use typeship docs search "<the message>".
Correct the source. If you cannot change an OpenAPI source, apply a Spec patch. Read the current patch list before replacing it.
Run generation again. Compare warnings and operation coverage, then inspect the affected generated methods. Clearing a warning does not prove the API accepts the request; test the relevant operation too.

Repair malformed YAML

For a local spec, --spec also accepts the complete file inline:

typeship packages generate \
  --spec "{\"inline\":$(jq -Rs . < openapi.yaml)}" \
  --target '{"type":"cli"}' --out ./generated/cli

For example, an accidental [ after paths: starts an unclosed YAML list:

paths: [
  /examples/petstore/pets:

Remove the [ so paths is a mapping, keeping its operation specs beneath it. Run the inline command again. A successful exit and files in generated/cli confirm the document parsed. If you are using the hosted Petstore spec, the repaired file should generate one operation. Build and call it:

cd generated/cli
go build -o petstore .
./petstore pets list --json --validate

The result is [{"id":"pet_1","name":"Mochi"}]. For your own API, use its generated read command and credentials. Check any remaining warnings separately from the repaired parse error.

Correct the reported problem

Finding	Consequence and correction
Relative server URL	Consumers must supply the base URL. Set an absolute API server URL when it is known.
Missing or duplicate `operationId`	Names are derived or disambiguated. Give operations distinct names that describe their purpose.
Unsupported security scheme	The generated client may lack the required authentication option. Check supported authentication.
`oneOf` without a discriminator	The generated type may be less precise. Add a discriminator only if it matches actual API behavior.

Specification compatibility explains how each construct maps to generated code. Diagnostics identifies broader authoring issues even when generation succeeds.

A missing operation can also be a coverage issue. Anonymous and Free generations include only 25 operations; the generated api.json lists the rest. A large MCP server may expose search, read, and execute tools instead of individual operation tools; in auto mode the switch occurs near 10,000 discovery tokens or above 100 operations. See MCP tool modes.

For AI agentsQuote the message verbatim when reporting an error. Propose the smallest supported source change or patch, regenerate, and compare the affected warnings and operations. A linked Draft can contain package customizations, but editing generated output does not repair a Spec diagnostic; fix the Spec or patch instead.

Fix a spec that will not generate

Inspect a generation

Repair malformed YAML

Correct the reported problem

On this page