Reference
Errors and warnings
Every message the generator can produce, quoted verbatim, with what to do about it. Errors stop generation. Warnings never do.
Generation fails hard only when the document cannot be used as a spec at all. Everything else generates, with warnings describing what was skipped or approximated. Messages are quoted exactly. A trailing ... stands for details filled in from your input.
Errors
These stop generation. On the typeship API they arrive as 422 with the code spec_error. In the console they appear where the generation would have.
| Error | What to do |
|---|---|
The spec is empty. | The input was blank. Paste the spec text, or check that the URL returns the document body. |
This looks like JSON but failed to parse: ... | The input starts with { or [ but is not valid JSON. The rest of the message is the parser error. |
Failed to parse as YAML: ... | Invalid YAML. The rest of the message is the parser error. |
The document parsed, but it isn't an object. An OpenAPI spec must be a JSON/YAML object with an \openapi` or `swagger` field.` | The top level is an array or a scalar. Paste the spec document itself, not a fragment. |
No \openapi` or `swagger` version field found. Is this an OpenAPI document?` | The document is an object without a version field. Usually something other than the spec was pasted, such as an API response or a JSON Schema. |
Unsupported Swagger version "...". Expected 2.0. | Only Swagger 2.0 is converted. |
Unsupported OpenAPI version "...". Supported: 2.0, 3.0.x, 3.1.x. | Re-export the spec as a supported version. |
The spec has no \paths` object, so there is nothing to generate.` | A components-only document has no operations. Point at the full spec. |
Failed to parse as GraphQL SDL: ... | The GraphQL schema did not parse. The rest of the message is the parser error. |
The GraphQL schema has no Query or Mutation fields, so there is nothing to generate. | Add root fields, or point at the full schema. |
Spec is larger than the 10MB limit. | The hard size cap, for pasted and fetched specs alike. Trim examples or descriptions. |
That doesn't look like a valid URL. | URL sources need an absolute URL with a scheme. |
Only http(s) URLs are supported. | Other schemes are rejected. Serve the spec over http(s) or paste it. |
Couldn't reach that URL. If the spec is behind auth, paste it instead. | The server-side fetch failed or exceeded 15 seconds. typeship sends no credentials, so specs behind auth must be pasted. |
The URL responded with HTTP <status>. If the spec is behind auth, paste it instead. | A 401 or 403 means the spec needs auth. A 404 usually means the URL points at documentation rather than the raw spec. |
Malformed request. | The request body sent to the generate endpoint was invalid. The console never produces this. It appears when calling the API with a wrong shape. |
The generator hit an unexpected condition in this spec. This is a typeship bug, not a problem with your spec. | Nothing to fix on your side. Retrying with a reduced spec narrows down which construct triggers it. |
Warnings
Warnings never block generation. They are attached to the result, shown in the console, and listed in regeneration pull requests. Counts, names, and operation lists are filled in from your spec.
| Warning | Meaning and fix |
|---|---|
Dropped request bodies declared on N GET/HEAD operations (...). GET bodies aren't reliably transmitted, so the SDK doesn't expose them. | The listed operations are generated without their request body. Move the fields to query parameters, or change the operation to POST. |
External $ref "..." is not supported. Treated as unknown. | References to other files or URLs are not fetched. The referenced schema becomes unknown. Bundle multi-file specs into one document. |
$ref "..." points nowhere. Treated as unknown. | A dangling local reference. Fix the pointer. |
Server URL "..." is relative. Pass \baseUrl` when constructing the client.` | The spec has no usable absolute server URL. The base URL becomes a required constructor option, and the CLI and MCP server need --base-url or the environment variable. Also reported as Server URL "..." has variables without defaults. Pass \baseUrl` when constructing the client.` |
N operations with binary/multipart bodies or streaming responses are SDK-only, not exposed in the CLI/MCP server (...). | File-upload payloads cannot ride flags or tool arguments, and event streams have no CLI or MCP rendering. Call these from code. |
The Python SDK does not support ... yet, so N operations were left out: ... | Reserved for a shape an emitter cannot express. Every body kind (JSON, form, multipart, binary, text), streaming, and GraphQL ship in all three languages today, so this does not currently fire; if it ever does, it names the reason and each operation, so a skipped endpoint is never silent. |
Security scheme "..." (...) isn't mapped to a client option. | An auth type outside bearer, basic, apiKey, OAuth2, and OpenID Connect. Pass credentials through defaultHeaders or the fetch option. |
Security scheme "..." has unsupported type "...". Skipped. | Swagger 2.0 only. Same fix. |
Shared parameter "..." is a body parameter. Inline it in each operation for full fidelity. Skipped. | Swagger 2.0 only. Shared body and formData parameters cannot be converted in place. |
Webhook "..." declares no JSON request body schema. Skipped. | Give the webhook a JSON request body schema and it becomes a typed event. |
globals: "..." matches no query or header parameter on any operation (path parameters aren't supported). Ignored. | A global parameter name that appears nowhere. Check the wire name. |
retries.operations: "..." matches no operation (use an operationId or "METHOD /path"). Ignored. | A retry or pagination key that matches nothing. Same for pagination:. |
pagination.<key>: itemsField is required. Falling back to detection. | A malformed pagination rule. The message names what is missing or wrong. Detection is used until the rule is fixed. |
Spec patch matched nothing, not applied: <op> <path> (<reason>) | A spec patch whose target no longer exists. Remove or update it. Similar messages report an append on a non-array, a rename on a non-key, and a rename whose destination exists. |
N spec patch(es) skipped: patches apply to OpenAPI documents, not GraphQL schemas. | Patches are configured on a GraphQL project. |
Output includes the first 25 operations; N more in this spec were not generated. | Free generation covers the first 25 operations of a spec, in spec order. Paid plans lift the cap. |
Python output is the SDK only; cli, mcp are generated from the TypeScript target. | The CLI or MCP server was requested with a Python or Go generation. They come from the TypeScript package. |
Limits
- Specs up to 10MB, pasted, uploaded, or fetched from a URL.
- A pasted spec travels in the request body and can be rejected by the platform's request cap before it reaches the generator. The homepage then shows
That spec is bigger than the hosted request limit (~4.5MB).Use a URL instead. The server fetches it directly and only the 10MB limit applies. - URL fetches follow redirects and time out after 15 seconds.
- Generated output over 3.5MB is delivered file by file on the API. See Plans and limits.