Fatal diagnostics

Fatal errors

The diagnostics above are reported — collected, sorted, and printed, with generation continuing unless a config error blocks it. The codes below are different: they are thrown, so the command stops at the first one and exits non-zero. They carry no severity because there is only one — fatal.

Configuration loading

Raised before validation, when the config file itself cannot be read.

Code	Meaning
`GLOTTO_CONFIG_NOT_FOUND`	No `glotto.yml` (or `glotto.yaml`) exists at the resolved path. Run the command from the directory holding your config, or point at it with `--config ./path/to/glotto.yml`.
`GLOTTO_CONFIG_YAML_PARSE`	The config file is not well-formed YAML. The error carries the `line` and `column` of the parse failure — a tab used for indentation and an unquoted `:` inside a value are the two usual causes.

The workspace file

Raised while reading a .glotto/workspace.json found by walking up from the current directory. A broken declaration is always reported — never quietly skipped in favour of some further-up project, which would run the command against an API you did not name.

Code	Meaning
`GLOTTO_WORKSPACE_INVALID`	The workspace file is not well-formed JSON, or does not match its schema — a missing `config`, a non-string path, or an unknown key. Unknown keys are rejected rather than ignored, so a typo cannot silently read as configured-and-working.
`GLOTTO_WORKSPACE_KEY_OWNED_ELSEWHERE`	The file sets `project` or `openapi_spec`. Neither is a workspace key in Glotto: `glotto.yml` already owns those values as `hosted.project` and `openapi.source`. The message names the key to move the value to. Most often seen when translating a Stainless `.stainless/workspace.json` by hand.
`GLOTTO_WORKSPACE_PATH_ESCAPE`	A declared `config` or `targets.<slug>` path is absolute, or escapes the workspace root with `..`. Declared paths are workspace-root-relative and must stay inside it.
`GLOTTO_WORKSPACE_CONFIG_MISSING`	The workspace file’s `config` names a file that does not exist. Both the declared path and the resolved absolute path are named.

Editor-only notes

Surfaced by the Glotto language server in your editor. These never affect a CLI exit code.

Code	Meaning
`GLOTTO_WORKSPACE_FOREIGN_CONFIG`	Information. The `glotto.yml` you have open is not the config declared by the `.glotto/workspace.json` above it — commands run from that workspace root will act on a different project. Add a workspace file beside this config to bind its own directory. Not a warning: the file still generates correctly.

Spec parsing and ingestion

Most codes here are raised while reading your API description, before the IR is built. GLOTTO_SPEC_REWRITE_BUDGET_EXCEEDED, GLOTTO_SPEC_REF_INTO_REWRITTEN_PATH and GLOTTO_SPEC_EXCLUDED_OPERATION_PUBLISHED are raised while preparing the published document. An exclude entry can trigger these refusals even when every path item is inline: a Link to an excluded operation, or a $ref into it, would point at removed content. When an edit changes a referenced path item, that item and any path items that read it through $ref are published as separate copies. Other references into changed content must be corrected before generation can continue. GLOTTO_SPEC_EXPANSION_BUDGET_EXCEEDED is raised while building the IR.

Code	Meaning
`GLOTTO_SPEC_UNSUPPORTED_VERSION`	The document declares an OpenAPI version Glotto does not support; 3.0.x and 3.1.x are supported. Swagger 2.0 is detected and auto-converted, so this names a genuinely unsupported version rather than an old one.
`GLOTTO_SPEC_PARSE`	The document could not be parsed. For OpenAPI the error carries the `line` and `column`; for GraphQL it carries the parser’s own message verbatim.
`GLOTTO_SPEC_INVALID`	The document parsed but is not usable: a required field is missing, an input handed to the GraphQL ingest is not a GraphQL document, or the document nests deeper than the supported limit (a guard against adversarially nested input). The message names which.
`GLOTTO_SPEC_SWAGGER2_CONVERT`	A Swagger 2.0 document was detected but the in-process 2.0 → 3.0 conversion failed. Convert it to OpenAPI 3.x first — with `swagger2openapi`, or the editor.swagger.io “Convert to OpenAPI 3” command — and retry.
`GLOTTO_SPEC_REWRITE_BUDGET_EXCEEDED`	Publishing the OpenAPI document with an `exclude` or with code samples gives each path item it edits, and each path item that reads one through a `$ref` (another path, a webhook, a callback), its own copy — and those copies would add more than 14,528,278 UTF-8 bytes of two-space-indented JSON, or 512,524 values (objects, arrays and primitives alike), or would nest deeper than the 64 levels Glotto reads. A spec reaches this when many paths share one large path item through `$ref`. Move what that path item holds into components of their own kind (`components.schemas`, `components.responses`, …) so each copy carries references rather than the content, and retry. The code leads the message, in `glotto generate` and in the hosted generation response alike.
`GLOTTO_SPEC_REF_INTO_REWRITTEN_PATH`	Publishing the OpenAPI document with an `exclude` or with code samples changes a path item, and a reference elsewhere — a `$ref`, a Link’s `operationRef`, a discriminator `mapping` value, or an OpenAPI 3.1 `$ref` or `$dynamicRef` naming a schema by `$id` (a relative one resolved against the `$id` enclosing it) or `#anchor` — points into the part it changed or removed, so it would name something else in the published document. Glotto refuses rather than guess what it should name now; the message names the reference’s location (and, for one inside a path item Glotto writes inline, where you wrote it) and its target. Point the reference at a `components` entry of its kind (`components.schemas`, `components.parameters`, `components.responses`, …) instead of into `paths` or `components.pathItems`, and retry. A Link to a code-sampled operation can name it by `operationId` instead; a Link to an excluded operation leads nowhere by any name — its `operationRef` or its `operationId` — so remove it or point it at an operation you keep. The same code refuses a path item that refers back into itself through a path the rewrite changes (move it into `components.pathItems` and reference it from both places), and a copy that would publish a second schema carrying one OpenAPI 3.1 `$id`, `$anchor` or `$dynamicAnchor` (move that schema into `components.schemas` and reference it). A reference that named nothing to begin with is left as it is, and `unresolved-ref` reports it — unless the rewrite would give it a target (its pointer crosses a `$ref`’d path item Glotto writes inline, or names the code samples it adds), which is refused too. The code leads the message, in `glotto generate` and in the hosted generation response alike.
`GLOTTO_SPEC_EXCLUDED_OPERATION_PUBLISHED`	An operation your `exclude` names would still be published, because something shares it: a webhook, an extension or another path names the `components.pathItems` entry it sits on whole, a path is written as a `$ref` to the excluded one, or a YAML alias writes the operation somewhere else too. Glotto refuses rather than publish it, so an `exclude` entry always withholds what it names. The message names the operation, where it would be published, and what keeps it there. Stop sharing the operation; the message identifies the path to give its own path item. When another path keeps the operation published, you can also exclude that path’s operation, which the message names. A webhook, a callback or an extension cannot be excluded, so there sharing has to stop. The code leads the message, in `glotto generate` and in the hosted generation response alike.
`GLOTTO_SPEC_EXPANSION_BUDGET_EXCEEDED`	Generating from the OpenAPI document would give its operations more than 518,160 values (objects, arrays and primitives alike) beyond what the document itself holds. Every operation is generated with its own copy of what it takes — its parameters, the path item’s and its own, its request body and its responses — so content many operations share is generated once per operation: a path item many paths reach through `$ref`, the parameters declared on it, or a parameter, request body or response they all reference. This budget bounds repeated parameter, request-body and response content at the reference readers; it does not bound the entire generation process. The same code is raised by a second budget, on the sample request values built for your operations: each operation’s sample is built from the schemas it names, so a schema with many properties, or one that fans out into several others, is walked again for every operation that uses it. Generating from the document would visit more than 212,992 schema positions across all of its operations’ samples, counting every 32 characters of an `example` or property name beyond its first 32 as one more position, so a long string repeated across many operations is charged by its length and the samples hold at most 64 characters per position of the budget. A single sample that is wider or deeper than 1,024 schema positions is not refused; it is shortened to its first 1,024 in document order. Give widely used schemas a short `example`, which is read rather than walked but whose text is counted, or reference them from fewer operations. Move large inline schemas into `components.schemas`, so each use carries a reference rather than the content, declare fewer parameters on a widely shared path item or share it among fewer paths, and retry. The code leads the message, in `glotto generate` and in the hosted generation response alike.

Spec source retrieval

Raised while fetching the spec, when openapi.source is not a plain local file. Each names the source it failed on.

Code	Meaning
`GLOTTO_SPEC_SOURCE_NOT_FOUND`	The spec source file does not exist at the given path.
`GLOTTO_SPEC_SOURCE_HTTP_STATUS`	A `url` source responded with a non-success HTTP status. The message names the final URL (after redirects) and the status.
`GLOTTO_SPEC_SOURCE_RESPONSE_TOO_LARGE`	A `url` source served a document larger than the 16 MiB response ceiling. The read stops at the limit rather than truncating, so nothing partial is ever parsed — host a smaller document, or point the source at a local file.
`GLOTTO_SPEC_SOURCE_AUTH_ENV_MISSING`	A source header references an environment variable that is not set in the running environment. Export it, or remove the header.
`GLOTTO_SPEC_SOURCE_FORBIDDEN_ADDRESS`	A `url` source was refused before any connection was made: its scheme is not `http(s)`, or its hostname resolves to a private, loopback, link-local, unique-local, or unspecified address. Checked on the initial URL and on every redirect hop. Use a publicly resolvable URL, or a local file source.
`GLOTTO_SPEC_SOURCE_GIT`	A `git` source operation failed. The message names the ref, the repository, and the underlying git error.
`GLOTTO_SPEC_SOURCE_COMMAND_SPAWN`	A `command` source binary could not be started — typically not on `PATH`. The message names the command.
`GLOTTO_SPEC_SOURCE_COMMAND_TIMEOUT`	The exporter command exceeded its wall-clock limit and was killed.
`GLOTTO_SPEC_SOURCE_COMMAND_OUTPUT_LIMIT`	The exporter command produced more output than the cap allows and was killed.
`GLOTTO_SPEC_SOURCE_COMMAND_EXIT`	The exporter command ran to completion but exited non-zero. The message carries the exit status and a bounded tail of its stderr.
`GLOTTO_SPEC_SOURCE_COMMAND_OUTPUT_PATH`	A `command` source’s file-output `path` is absolute or escapes its working directory via `..`. Refused without reading outside the working directory; use a relative path inside it.
`GLOTTO_SPEC_SOURCE_COMMAND_NO_OUTPUT`	The exporter command succeeded but wrote no file at the declared output path.
`GLOTTO_SPEC_SOURCE_INTROSPECT_PATH`	An `introspect` source `path` does not exist or is not a directory. Refused before any analysis runs.

Transform engine

Raised while applying the transforms block to your spec. Each error carries the transform name, its transform_index in your list, and the target it was resolving — so a failure in a long transform chain names the exact entry.

Code	Meaning
`GLOTTO_IR_TRANSFORM_TARGET_NOT_FOUND`	The transform’s `target` matched nothing in the spec. Usually a typo or a schema renamed upstream.
`GLOTTO_IR_TRANSFORM_TARGET_AMBIGUOUS`	The `target` matched more than one candidate, so the transform will not guess. Narrow it until it names exactly one.
`GLOTTO_IR_TRANSFORM_INVALID_ARGUMENT`	An argument is not valid for that transform — the message names the argument and what it expected.
`GLOTTO_IR_TRANSFORM_SPEC_DEPTH_EXCEEDED`	The transform’s walker hit the nesting-depth cap while traversing the spec (the same guard as `GLOTTO_SPEC_INVALID`’s depth check, applied during transformation).
`GLOTTO_IR_TRANSFORM_TARGET_INVALID_EXPRESSION`	An `apply_overlay` action’s JSONPath `target` is malformed or violates a rule the supported RFC 9535 subset refuses — for example, comparing a many-node query directly or using regex syntax outside I-Regexp. The message names the construct and its character offset. It is deliberately not reported as “matched nothing” — a target we cannot parse is a broken target, not a changed spec.
`GLOTTO_IR_TRANSFORM_OVERLAY_SOURCE_UNREADABLE`	An `apply_overlay` or `merge_document` entry references a document (`source:`) that could not be loaded — a missing file, an unreachable or blocked URL, a git ref that will not clone. The message carries the underlying reason. Check the path is relative to your `glotto.yml`, and that a URL host is publicly reachable.
`GLOTTO_IR_TRANSFORM_OVERLAY_DOCUMENT_INVALID`	A referenced overlay document loaded but is not an Overlay Object — unparseable YAML/JSON, a non-object root, or an `actions` that is missing, not an array, or empty. An empty overlay is treated as a broken reference rather than as “apply nothing”, for the same reason a target matching nothing stops the build.
`GLOTTO_IR_TRANSFORM_MERGE_DOCUMENT_INVALID`	A `merge_document` entry’s document loaded but is not usable — unparseable YAML/JSON, a root that is not an object, or an empty object. A merge document is a partial OpenAPI document, so any key is legal, but it must be an object and it must declare at least one key: an empty one is a broken reference rather than “merge nothing”.
`GLOTTO_IR_TRANSFORM_MERGE_DOCUMENT_INERT`	A `merge_document` entry changed nothing — the spec already asserts every value the document declares, so the correction is dead. Usually this means your upstream spec has caught up with the override. Delete the entry, or point it at the document you meant. The check is per entry, not per key, so a document with one key that still bites is fine.
`GLOTTO_IR_TRANSFORM_MERGE_DOCUMENT_STRICT_VIOLATION`	A `merge_document` entry set `strict: true`, which asserts the document only corrects and never adds — and at least one of its leaves names a path your spec does not have. The message lists every offending path, not just the first, so one run clears one round of typos. Usually a misspelled key (`descriptoin`), which without `strict` would have been silently added as a new node. Fix the path, or drop `strict` if the entry is genuinely meant to extend the spec.
`GLOTTO_IR_TRANSFORM_OVERLAY_EXTENDS_MISMATCH`	An overlay’s `extends` names a different document than the URL your `openapi.source` points at, so its corrections were written for another API. The message carries both spellings. If the overlay does belong to this API, delete the optional `extends` field — Glotto always overlays the configured input source and never fetches `extends`; otherwise point `openapi.source` at the document the overlay was written for. Only checked when `openapi.source` is a URL: against a local file there is nothing comparable to check against, and the verification report records that as `unverifiable` rather than implying a check that did not run.
`GLOTTO_IR_ALLOF_CONFLICT`	IR construction could not merge an `allOf` composition. Either two members declare the same property with structurally different types (the message names the property and both types), two members disagree on `type`, or the `allOf` chain is cyclic (the message names the cycle). Glotto refuses rather than picking one, because which member won would depend on declaration order in a way nothing in your generated SDK would reveal. Reconcile the two declarations in your spec, or split the conflicting property into distinct names.
`GLOTTO_CONFIG_ENUM_NAMING_ILLEGAL_IDENTIFIER`	An `enum_naming` entry in `glotto.yml` names an identifier that cannot compile in the language it is aimed at — it is not a legal identifier there, it is a reserved word in that language (`new` in Dart, Java, Kotlin, C#, PHP or Swift; a leading digit or punctuation anywhere), or it does not begin with an uppercase letter where that is what makes it a member at all — a Ruby name that does not start `[A-Z]` is a local variable rather than a constant, and a lowercase Go constant is unexported, so both compile or parse while declaring nothing your callers can reach — or it spells a name the SDK itself declares beside the members of every enum (Ruby `ALL`, C# `IsKnown` and `Value`, Dart `isKnown` and `value`), which would overwrite or collide with it. The message names the exact path so you can find it in your `glotto.yml`: `enum_naming.<model>.<value>.<slug>` when you pinned that language explicitly, and `enum_naming.<model>.<value>` when you wrote one logical name — there is no per-language key in your file in that case, so changing the logical name is the fix. Glotto refuses rather than quietly adjusting the name, because an identifier you wrote explicitly is one your callers read: silently emitting `new_` would give your SDK a public constant you never chose. Pick an identifier that compiles in that language, or drop the per-language entry and let Glotto derive the name. The check is per target, so a spelling that is legal in Python and reserved in Dart is refused only for Dart.
`GLOTTO_CONFIG_ENUM_NAMING_DUPLICATE_IDENTIFIER`	Two `enum_naming` entries for the same enum name the same identifier for the same target language, so the emitted enum would declare that member twice — `error[E0428]` in Rust, `CS0102` in C#, a duplicate `case` elsewhere. Each identifier is perfectly legal on its own, which is why this is a separate code from `GLOTTO_CONFIG_ENUM_NAMING_ILLEGAL_IDENTIFIER`: nothing here fails to compile in isolation. The message names the path of the second entry and the value that already holds the spelling. Glotto refuses rather than bumping one to `InProgress_`, because both names are ones you wrote and an explicit name is never auto-renamed. Pick a different identifier for one of them. The check is per target, so the same spelling for two different languages is not a collision.
`GLOTTO_IR_UNSUPPORTED_SCHEMA`	IR construction structurally rejected a schema shape it cannot represent. Not a transform failure — it is raised by the IR build itself, and the message names the offending schema. OpenAPI 3.1 type arrays may contain one concrete type plus `null`; use an explicit `oneOf` or `anyOf` for multiple distinct non-null types. An `allOf` combining an independent union with another shape is also refused because merging would discard alternatives; express an explicit union whose object variants each contain the shared properties. An API-key security scheme the IR cannot carry (a cookie scheme, a missing or unrecognised `in`, a missing or empty `name`, or an AsyncAPI `user` or `password` location) is refused when the SDK would read it: when it is in the first requirement of the top-level `security` or of an operation (an `and` of several schemes counts), or when it is the scheme the SDK would otherwise default to (no top-level `security` naming a declared scheme) and an operation inherits that default. The IR supports a header or query key with its declared name only, so it would otherwise send the key as a header credential under an invented name, or fall back to bearer. A later alternative of an `or` of requirements, a webhook or callback `security`, and a scheme nothing reads are ignored. Choose an authentication scheme supported by both the API and generator. Local security references are resolved before this check; inline or resolve missing, external or cyclic security references before generation.
`GLOTTO_IR_WIRE_NAME_NOT_TOKEN`	A header parameter, a cookie parameter, or an API-key security scheme carried in a header declares a name that HTTP cannot send. For a required header or cookie parameter, or an API key carried in a header, the generated SDK would compile and then fail or mis-send its first request. A header name must be an RFC 9110 `token`, and a cookie name an RFC 6265 `cookie-name`, which is the same `token`: ASCII letters, digits and the characters ! # $ % & ' * + - . ^ _ ` ~ and the vertical bar, nothing else. Brackets (`filter[status]`), spaces, `;` `,` `=` `:` `/`, quotes, control characters, non-ASCII letters (`Straße`) and the empty string are all outside it. The message lists every offender with its location (header parameter, cookie parameter or API-key scheme), the operation (name, HTTP method and path) or the scheme, and the name quoted exactly, and the build refuses before any target — SDK, MCP server, docs site or CLI — is written. Glotto refuses rather than rewriting the name, because any rewrite would send a name your API’s contract does not contain. Correct the name in your spec (an `apply_overlay` or `merge_document` transform can do it without editing the source) or remove the parameter. An optional parameter is checked too: no SDK engine sends it, but the CLI target does and the docs list it, and the message says so beside that parameter. An API-key header scheme that no operation selects is checked too: nothing sends it today, but every SDK engine compiles the name into its auth code, so the first operation that adopts the scheme fails, and the message says that beside the scheme. Path and query parameter names are not checked. A cookie API-key scheme is refused separately, under `GLOTTO_IR_UNSUPPORTED_SCHEMA`.

Object query serialization

Raised during SDK generation when a declared object query cannot be represented by a supported wire format. The error names the parameter; generation stops before emitting an SDK with misleading query values.

Code	Meaning
`GLOTTO_ARRAY_HEADER_UNSUPPORTED`	An array header parameter uses a style other than `simple`, or declares elements that are not strings, integers, numbers, booleans or enums (an array of arrays or of objects has no header representation). Use a flat list of scalar values with the default `simple` style; `explode` makes no difference for an array.
`GLOTTO_OBJECT_PARAMETER_UNSUPPORTED`	An object header or cookie parameter uses an unsupported style or declares nested object/array values. Use flat objects or maps of scalar values: `simple` for headers and `form` for cookies, with either explode value.
`GLOTTO_OBJECT_QUERY_UNSUPPORTED`	An object query uses an unsupported `style` / `explode` combination or declares nested object/array values. Use a flat object or a map of scalar values with `deepObject` and `explode: true`, or `form` with either explode value. An omitted style uses `form`; an omitted explode value uses the supported true baseline. A nested object, map or array member is refused until you set `query_settings.nested_format` to `brackets` or `dots`. Even with it set, these stay refused, naming the parameter and member path: a nested member under `form` with `explode: false`, a union with two or more non-null variants of which any is non-scalar (a union of one variant and `null` is accepted as that variant), and a member name or map key containing the active format’s delimiter (`[` or `]` for `brackets`, `.` for `dots`). Rename the member or choose the other format.
`GLOTTO_SDK_DEPENDENCY_CONFLICT`	A dependency in `targets.<language>.dependencies` conflicts with a package required by the generated SDK. Remove the named declaration or copy the generated requirement exactly. For a Swift package identity collision, use the generated package URL and requirement, then name the desired product after `#`. No output is written until the conflict is resolved.

Hosted generation

Raised by the hosted generation service (POST /v1/codegen and the jobs behind it), never by a local glotto generate. Each runs your spec in its own resource-bounded process, and a request that exceeds a bound is refused with the code leading the message instead of being left to take other requests down. The code leads the diagnostic text in glotto generate and in the hosted response alike.

Code	Meaning
`GLOTTO_CODEGEN_TIMEOUT`	Generation did not finish inside the hosted service’s time limit and was stopped. The request is refused with HTTP 422 and, for a queued job, the job fails. A very large spec, or one that expands heavily during generation (many operations sharing large inline schemas), is the usual cause; move large inline schemas into `components.schemas`, narrow `targets`, and retry.
`GLOTTO_CODEGEN_MEMORY_EXCEEDED`	Generation used more memory than the hosted service allows a single request and was stopped. HTTP 422; a queued job fails. The causes and fixes are those of `GLOTTO_CODEGEN_TIMEOUT`: reduce what the spec expands into, or generate fewer targets per request.
`GLOTTO_CODEGEN_OUTPUT_TOO_LARGE`	The generated output is larger than the hosted service returns in one response. HTTP 422; a queued job fails. Generate fewer targets per request, or exclude operations the SDK does not need.
`GLOTTO_CODEGEN_WORKER_CRASHED`	The generation process stopped without producing a result, for a reason other than the time, memory and output limits above. This is a fault on Glotto’s side, not in your spec: HTTP 500, and a queued job fails. Retrying is reasonable; if it recurs for the same spec, report it with the request time.
`GLOTTO_CODEGEN_INPUT_TOO_LARGE`	The request body is larger than the hosted body limit. HTTP 413, returned before the body is validated and before any generation starts. Reduce the size of the spec or config you send, for example by removing content the SDK does not need.
`GLOTTO_CODEGEN_CAPACITY_EXHAUSTED`	Every generation slot was busy for longer than the request may wait. HTTP 503 with a `Retry-After` header on a synchronous request, and a failed job for queued work. Nothing is wrong with the spec; retry after the interval given.
`GLOTTO_CODEGEN_NOT_SERVED`	The deployment that received the request does not run code generation. HTTP 501 with no `Retry-After`, because retrying the same deployment cannot succeed; send the request to the hosted service’s generation endpoint.