Reference
Spec errors and warnings
The messages the generator returns for a Spec it cannot use, and the warnings it attaches to a Generation, quoted verbatim with what to do next.
This page explains the message text. The API error code that carries it, such as spec_invalid, is listed with its status and retry behavior in Errors. The common messages below are quoted exactly. A trailing ... stands for details filled in from your input; less common messages carry their fix in the text itself.
Generation fails only when the document cannot be used as a Spec at all. Everything else generates, with warnings describing what was skipped or approximated.
Spec content errors
These stop generation. On the Typeship API they arrive as spec_invalid, except the size limit, which is spec_too_large. In the console they appear where the Generation would have.
| Message | 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. |
Invalid GraphQL schema: ... | The GraphQL SDL or introspection result did not parse or validate. The rest of the message is the GraphQL error. |
This looks like JSON but has no __schema, so it is not GraphQL introspection output. | Send the complete introspection result, including __schema, or the SDL instead. |
The GraphQL schema has no Query or Mutation fields, so there is nothing to generate. | Add root fields, or point at the full schema. |
The Spec is 26 MB; the limit is 10 MB. | The hard size cap for Specs fetched by URL, across all of their documents. Remove unused operations or examples, or split the Spec and generate each part. |
The inline Spec is 6.9 MB; inline Specs are limited to 4 MB. | A pasted or spec.inline Spec travels in the request body. Send it with spec.url instead; URL Specs may be up to 10 MB. |
The Spec URL returned JSON or YAML without a top-level openapi or swagger field | The URL returned a structured document that is not an OpenAPI description. Check that it points at the Spec file itself. |
Spec URL errors
These stop generation before the document is read. On the Typeship API they arrive as spec_unreachable.
| Message | What to do |
|---|---|
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. |
Spec URLs cannot contain embedded credentials. | Remove the user and password from the URL. For a protected source, send the credentials as write-only request headers. |
Couldn't reach that URL. | The server-side fetch failed, exceeded 15 seconds, or did not resolve exclusively to public network addresses. Check the URL and network path. Protected sources can send write-only request headers. |
The Spec URL responded with HTTP <status>. | Check the source URL for a 404 or 410. For a 401 or 403, add the required request header under protected source. |
The Spec URL responded with HTTP <status> to GET, and GraphQL introspection failed: ... | The URL returned no document, so Typeship also tried it as a GraphQL endpoint. For an OpenAPI or SDL file, fix the URL from the status. For a GraphQL endpoint, the rest of the message explains why introspection failed. |
The Spec URL did not return an OpenAPI document or GraphQL SDL, and GraphQL introspection failed: ... | The URL returned a page, such as HTML documentation or an API response, that is not a Spec, and it is not a GraphQL endpoint either. Point at the raw OpenAPI or SDL file. |
Spec file <path> responded with HTTP <status>. | A document the entrypoint references could not be fetched. Couldn't reach that Spec URL. reports the same for a network failure. Fix the reference or the file's location; see Combine API documents. |
Warnings
Warnings never block generation. They are returned in the Generation's warnings, shown in the console, and listed in Draft 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. | This is a parser fallback for a reference that reached generation unresolved. URL and repository Specs resolve supported external references before parsing: same-origin URLs or files inside the connected repository. For an inline multi-file document, provide the URL or repository entrypoint instead, or bundle it before sending. Check the reference boundary and source errors in Combine API documents and Spec compatibility. |
$ref "..." points nowhere. Treated as unknown. | A dangling local reference. Fix the pointer. |
N $refs point to nothing in the spec, so their types are unknown: ... | Every dangling local reference in the document, including those under webhooks and x-webhooks, named (the first 20, then a count). Add the missing components or fix the references; until then those payloads are untyped. |
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 uploads or streaming responses are limited as MCP tools ... | Uploads remain available in the CLI and package's local MCP server through file paths, and in every SDK. A remote MCP server cannot read the caller's files. Event streams remain available in the CLI and every SDK; MCP does not support them. The warning names each affected operation. |
The Python SDK does not support ... yet, so N operations were left out: ... | Reserved for a shape an emitter cannot express. The equivalent Go warning names the Go SDK. Every body kind and GraphQL currently ship in all three languages; if a future limitation applies, no endpoint disappears silently. |
Security scheme "..." (...) isn't mapped to a client option. | Mutual TLS, HTTP Digest, or another scheme generated clients cannot send. CLIs and MCP servers refuse operations that only accept it. In an SDK, add the credential with a custom fetch (TypeScript), transport (Python), or WithHTTPClient (Go). |
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. |
Webhook signatures could not be determined: ... The SDKs parse webhook payloads but do not verify them ... | The webhooks declare a signature header in a format the SDK does not verify, or headers without a signature. The SDKs generate parsers only. See Check your signing contract. |
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. |
Go module path "..." is generated as ".../vN" to match version ... | Go requires a v2 or later module path to end in its major version, such as /v2. Typeship adds the suffix to the configured module_path so go get resolves. Import the SDK from the suffixed path. |
license "..." is recorded in the package metadata but no LICENSE file was written: only MIT is built in. Pass licenseText with the exact text of the licence to ship the file. | The registry metadata has an SPDX id, but Typeship cannot invent the legal text. Add config.package.license_text. MIT is built in when a copyright line is also configured. |
Limits
- Specs up to 4MB pasted or sent inline, and up to 10MB fetched from a URL. A pasted Spec travels in the request body; the platform refuses any request over 4.5MB before it reaches Typeship. Use a URL for larger Specs: the server fetches it directly and only the 10MB limit applies.
- URL fetches follow at most five redirects, require a public network destination at every hop, stream at most 10MB, and time out after 15 seconds across the complete request.
- Generation responses list file paths and sizes. Read content through the file endpoint. See Generations.