Diagnostic codes

Every diagnostic tungsten reports has a stable code, TGnnnn. The first two digits after TG name the area. tungsten explain TGnnnn prints the text below for one code. This page is generated from the compiler's registry.

Parsing and input limits (TG01xx)

TG0101

input file could not be read

Meaning. An input named in tungsten.yml or on the command line could not be read: the file does not exist, is a directory, or is not readable by the current user.

Fix. Check the path. Paths in tungsten.yml are relative to the directory of tungsten.yml, not to the working directory.

TG0102

input is not valid JSON or YAML

Meaning. The input is neither valid JSON nor valid YAML, so no OpenAPI document could be read from it. The message names the first syntax error.

Fix. Fix the syntax error at the reported position. Run the file through a JSON or YAML linter if the position is not obvious.

TG0103

unsupported OpenAPI version (convert Swagger 2.0 to OpenAPI 3 first)

Meaning. The document's openapi field is missing or names a version tungsten does not compile. tungsten reads OpenAPI 3.0.x and 3.1.x; Swagger 2.0 documents declare swagger: "2.0" instead.

Fix. Set openapi to the version the document follows, or convert a Swagger 2.0 document to OpenAPI 3 (for example with swagger2openapi) before compiling.

TG0104

document is missing a required OpenAPI field

Meaning. A field the OpenAPI specification requires is absent (for example info, info.title, info.version, or a parameter's name or in).

Fix. Add the field at the reported pointer.

TG0105

input exceeds a size or nesting limit

Meaning. The input is larger than the configured byte limit or nests deeper than the depth limit. The limits protect the compiler from pathological or hostile inputs.

Fix. Split very large documents into files joined by $ref, or flatten deeply nested inline schemas into named components.

TG0110

document has no info.version; version 0.0.0 is used

Meaning. The document has no info.version. OpenAPI requires it, but published specs sometimes omit it. tungsten records version 0.0.0 and continues; the diagnostic is a warning, and the document is still refused when something else required is missing.

Fix. Add info.version to the document, or supply it with an overlay.

TG0111

path key carries a query string; its pairs are sent on every call

Meaning. A key of paths carries a query string, such as /v1/messages?beta=true. OpenAPI forbids it, but some APIs use it to select a variant of an operation. tungsten names the operation and places it in resources from the path alone, keeps the query pairs as constant query parameters of the path template (path.query in the IR), sends them on every call (they are not arguments), and the mock routes a request only to the operation whose constants it carries.

Fix. No change is needed. To make the document valid OpenAPI, declare the pair as a query parameter with a const or enum schema.

TG0112

apiKey header scheme inferred from a credential header parameter

Meaning. The document defines no security scheme and no security, but declares a header that carries an API key (x-api-key, api-key or apikey) as a parameter. tungsten inferred an apiKey header scheme named apiKey and required it by every operation, so the credential is configured once on the client and the header is no longer an argument of each call.

Fix. Define the scheme under components/securitySchemes and list it in security (an overlay can add both) to make the intent explicit and silence the diagnostic.

References and cycles (TG02xx)

TG0201

unresolvable $ref

Meaning. A $ref points at a location that does not exist: the JSON Pointer names a missing member, or the referenced file has no such path.

Fix. Correct the pointer (pointers are case-sensitive and escape / as ~1 and ~ as ~0), or add the missing definition.

TG0202

remote $ref blocked (remote fetching is not available)

Meaning. A $ref names a remote URL. This version of tungsten does not fetch remote references, so that compiling never depends on, or leaks to, other hosts.

Fix. Vendor the remote document next to the spec and reference it by relative path.

TG0203

circular $ref through named types (recursion preserved)

Meaning. Named schemas reference each other in a cycle. This is legal; the cycle is kept and the participating types are marked recursive so emitters box or lazily evaluate the recursive edges.

Fix. Nothing to fix. The note exists so recursive types are visible in review.

TG0204

$ref to an external file outside the input root

Meaning. A $ref points at a file outside the directory tree of the input, which tungsten refuses to read.

Fix. Move the referenced file under the input root, or point the manifest at a common parent directory.

TG0205

circular $ref without a named type to break the cycle

Meaning. A reference cycle runs through inline schemas only, so there is no named type at which generated code could break the recursion.

Fix. Move the recursive schema under components/schemas and reference it by name, or list the edge in tungsten.yml types.break_cycles (for example Node.children).

TG0206

overlay target matched nothing

Meaning. An overlay action's target JSONPath matched no node in the document, so the action had no effect.

Fix. Fix the JSONPath expression, or remove the action if the spec no longer contains the node it was written for.

TG0207

overlay document or action is invalid

Meaning. An overlay file is not an OpenAPI Overlay 1.x document, has no actions array, or contains an action without a valid target JSONPath, so it could not be applied.

Fix. Start the file with overlay: 1.0.0 and an info block, list the changes under actions, and give each action a target JSONPath plus update or remove.

Type normalization (TG03xx)

TG0301

untagged union: runtime will sniff candidates in order

Meaning. A oneOf or anyOf has no discriminator, so a value's variant can only be found by trying the candidates in order at runtime. The order is deterministic (most constrained first), but sniffing is slower and can pick the wrong variant when candidates overlap.

Fix. Add a discriminator with a property every variant declares as a const or single enum value.

TG0302

allOf members conflict and could not be flattened

Meaning. The members of an allOf declare the same property with incompatible types, or mix records with non-records, so they cannot be merged into one record. The type is kept as an intersection, which some targets express poorly.

Fix. Make the overlapping property types agree, or restructure the schema so allOf only combines compatible records.

TG0303

unsupported or unknown schema keyword ignored

Meaning. A schema uses a keyword tungsten does not model (for example not, if/then/else or patternProperties). The keyword is ignored, so generated validation is looser than the spec.

Fix. Nothing is required. If the constraint matters to clients, express it with supported keywords or document it in the description.

TG0304

unknown string format treated as plain string

Meaning. A string schema uses a format tungsten does not recognize. The value is treated as a plain string and the format name is preserved in the IR.

Fix. Use a standard format (uuid, date-time, email, ...) if one fits; otherwise the warning can be accepted.

TG0305

schema type could not be determined; treated as any

Meaning. A schema has no type and nothing else (enum, const, properties, items, composition) from which a type could be inferred, so it accepts any value.

Fix. Add a type, or an explicit empty schema {} if any value really is allowed.

TG0306

discriminator could not be applied as written

Meaning. A discriminator next to oneOf/anyOf could not be used as written: it has no propertyName, a variant is not an object schema, a mapping entry does not resolve or names a schema that is not one of the variants, or a variant has no tag value. Unusable mapping entries are dropped; an unusable discriminator is ignored and the union is classified as if it had none.

Fix. Point every mapping value at one of the union's variants (#/components/schemas/X or the bare name X), and make every variant an object schema with the property.

TG0307

schema admits no value (empty enum or union)

Meaning. A schema admits no value at all: an empty enum, or a oneOf/anyOf with no members. Its type is never, so no generated client can send or accept it.

Fix. List the allowed values, or remove the schema if it is unused.

TG0308

types.break_cycles entry names no component property

Meaning. An entry of tungsten.yml types.break_cycles does not name a property of a schema under components/schemas (entries have the form Type.field), so it has no effect.

Fix. Fix the entry to Type.field with the component key and property name as written in the spec, or remove it.

Naming (TG04xx)

TG0401

identifier collision disambiguated

Meaning. Two names in one scope (fields of a record, operations of a resource, types of a namespace) map to the same identifier in some target language. The later one in sorted order was renamed deterministically.

Fix. Rename one of them in the spec, or give an explicit name in tungsten.yml naming, so the generated name is chosen rather than derived.

TG0402

identifier escaped (reserved keyword or invalid start)

Meaning. A name is a reserved word in a target language or does not start with a letter, so it was escaped (for example type becomes type_ in Python and Rust). The wire name is unchanged.

Fix. Nothing is required. Rename in tungsten.yml naming if the escaped form reads badly.

TG0403

operation has no operationId; name synthesized

Meaning. An operation has no operationId, so its id and method name were synthesized from the HTTP method and path. Synthesized names change when the path changes.

Fix. Add an operationId to the operation so its id stays stable.

Operations, pagination and auth inference (TG05xx)

TG0501

pagination inferred by heuristic

Meaning. No explicit pagination was configured and the operation matched a heuristic: cursor (a closed response record with one array field and one nullable next_* field, and a query parameter of the same name), or offset/page (offset and limit, or page and a page size, with an array of items). Generated SDKs will iterate pages.

Fix. Confirm the inference, or declare the operation under tungsten.yml pagination (use none: true to switch inference off for it).

TG0502

security scheme referenced but not defined

Meaning. An operation's security requirement names a scheme that is not defined under components/securitySchemes, so tungsten cannot tell how to authenticate it.

Fix. Define the scheme under components/securitySchemes, or fix the name in the requirement.

TG0503

composite auth profile satisfies an undefined security scheme

Meaning. A composite auth profile in tungsten.yml lists under satisfies a name that is not a security scheme of any input, so the profile cannot stand in for it.

Fix. List the scheme names the operations' security requirements use (from components/securitySchemes), and add parts that supply them.

TG0504

operation excluded by include predicate (planned)

Meaning. The operation does not match the input's include predicate, so it is not callable. When it matches planned_from it is recorded as planned for documentation.

Fix. Nothing is required. Change the predicate or the operation's extension value if the operation should be callable.

TG0505

runtime gate recorded from x-runtime-gate

Meaning. The operation carries x-runtime-gate, so it only works when the server enables the named gate. Generated clients report the gate instead of a bare 404.

Fix. Nothing is required. Describe the gate under agent.yml gates so agents get a useful explanation.

TG0506

rpc_unflatten target not found or not a const-discriminated oneOf

Meaning. The input's rpc_unflatten names a path and method that do not exist, or whose request body is not a oneOf discriminated by a const method field, so it cannot be split into one operation per method.

Fix. Check rpc_unflatten.path, method, discriminator and params against the spec.

TG0507

path template parameter without a definition; assumed a required string

Meaning. A path template names a {param} that no path-level or operation-level parameter declares. The SDK treats it as a required string so the operation stays callable.

Fix. Declare the parameter with in: path, required: true and a schema.

TG0508

malformed operation element ignored

Meaning. Part of an operation does not have the shape OpenAPI requires and was skipped: a parameter without name or in, a path parameter missing from the template, a response key that is not a status code, NXX range or default, or a member that must be an object or array but is not.

Fix. Fix the element at the reported pointer; the message names what is wrong.

TG0509

unsupported security scheme ignored

Meaning. A security scheme uses a type tungsten cannot generate authentication for (for example mutualTLS or an HTTP scheme other than bearer and basic), or lacks a field its type requires. Requirements naming it stay in the IR without a scheme.

Fix. Describe the credential with a supported scheme, or authenticate those operations through a custom transport.

TG0530

event stream declares no schema; events decoded as any JSON value

Meaning. A success response declares the text/event-stream media type without a schema, so the SDK cannot type or check the events of the stream. Each event's data is still decoded as JSON and handed to the caller as an untyped value.

Fix. Declare the schema of one event under the media type (usually a oneOf tagged by a type property). Name a data value that ends the stream, if there is one, with x-tungsten-stream-done.

TG0531

event stream declared for more than one success status; the first is streamed

Meaning. More than one success status of an operation declares text/event-stream. The SDK streams the lowest status; the others are read as plain responses.

Fix. Declare the stream under one status, normally 200.

TG0570

invalid MCP embedding index configuration (search.embeddings); the index is off

Meaning. targets.mcp.search.embeddings in tungsten.yml is not valid: an unknown key, a provider that is not command or http, a missing command, url or model, a dimensions, batch_size or timeout_ms out of range, or an api_key_env that is not an environment variable name. The embedding index is off and the MCP server searches with BM25 only; with required: true this is an error instead.

Fix. Fix the option: search: { embeddings: { provider: command, command: "node embed.mjs", model: my-model } } or provider: http with url. See the MCP server guide for embedding provider examples.

TG0571

embedding provider could not be run or did not answer in time; BM25 only

Meaning. The embedding provider of the MCP target could not be used: the command was not found, could not be started, exited with a failure, or neither it nor the HTTP endpoint answered within timeout_ms. Generation went on without index.embeddings.bin and index.embeddings.json, so the server searches with BM25 only. With required: true this is an error and nothing is written.

Fix. Run the command by hand with a request on standard input ({"protocol":1,"kind":"document","model":"m","dimensions":null,"inputs":["x"]}), raise timeout_ms, or lower batch_size.

TG0572

embedding provider returned an invalid response; BM25 only

Meaning. The embedding provider answered, but not with what the protocol says: not JSON, no embeddings array (command) or data array (HTTP), a different number of vectors than inputs, vectors of different or unexpected lengths, or values that are not finite numbers. Generation went on with BM25 only (an error with required: true).

Fix. Return one vector per input, in order, all of the length the model produces; set dimensions to that length so a mismatch is caught.

TG0573

embedding endpoint refused the request, needs a missing API key or uses https; BM25 only

Meaning. The HTTP embedding provider could not be called: the endpoint answered with an error status, the environment variable named by api_key_env is not set, or the URL is https://, which the compiler cannot call (it links no TLS stack). Generation went on with BM25 only (an error with required: true). The key is only ever read from the environment and never written to the output.

Fix. Export the API key, check the URL and model, or use provider: command with a program that calls the endpoint (for example curl) or a local http:// gateway.

TG0574

embedding index written next to the MCP manifest

Meaning. The MCP target wrote the embedding index: index.embeddings.json (model, dimensions, tool names and content hashes, checksum) and index.embeddings.bin (normalized little-endian f32 vectors). Vectors of tools whose text did not change since the previous run are reused, so only new or edited tools reach the provider.

Fix. Nothing to fix. Serve the index with search.embeddings in the server options (the generated server.ts sets it from tungsten.yml).

Manifests (TG06xx)

TG0601

manifest is not valid YAML

Meaning. A manifest (tungsten.yml or agent.yml) is not valid YAML.

Fix. Fix the YAML syntax at the reported position. Indentation must use spaces.

TG0602

manifest does not match its schema

Meaning. A manifest is valid YAML but does not match its schema: a key is unknown, a required key is missing, or a value has the wrong type. The pointer names the offending node.

Fix. Correct the value at the pointer. Editors with the YAML language server validate against the schema named in the file's first-line comment (tungsten schema tungsten prints it).

TG0603

manifest references an unknown operation

Meaning. A manifest refers to an operation id that does not exist in the compiled API.

Fix. Use namespace.operationId; tungsten explain <id> shows whether an id exists.

TG0604

manifest references an unknown namespace or path

Meaning. A manifest refers to a namespace, resource or path that does not exist in the inputs.

Fix. Check the name against inputs[].namespace in tungsten.yml and the paths of the spec.

TG0605

agent rule targets an operation that cannot serve it

Meaning. An agent rule points at an operation that cannot do what the rule needs: a verification hook or a macro poll step names an operation that is not read_only (the runtime would repeat its side effect), a paginate step names an operation without pagination, or an endpoint preview names the operation itself. The rule (or the macro) is dropped.

Fix. Point the rule at a read_only operation (for a poll or a verification hook), at a paginated one (for paginate), or declare the operation's safety or pagination if the inferred one is wrong.

TG0606

remediation names an unknown error code

Meaning. A remediation entry in agent.yml (errors.codes or a tool's remediation) or in x-agent-remediation is keyed by an error code that the error model of the operation's namespace (or of any namespace, for errors.codes) does not list. The entry is kept but may never match a response.

Fix. Use a code from the error schema's code enum (tungsten ir dump shows namespaces[].errors.codes), or fix the spelling.

TG0607

agent rule names a field the operation does not have

Meaning. An agent rule names a field that does not exist: a confirmation summary field or message placeholder that is not a request parameter or body field, a sensitive field that is not in the success response, a verification argument or predicate path, a macro reference such as $accepted.message_id into a step's response, or the code field of errors.envelope.

Fix. Use the wire names of the spec (dotted for nested fields, for example key.action_id); tungsten explain <operation> lists an operation's parameters and body.

TG0608

gate names no runtime gate or conflicts with the spec

Meaning. A tool's gate names neither an x-runtime-gate environment variable of the spec nor a gates entry, or the operation is already gated by a different variable, or a gates entry's disabled_status disagrees with the spec's gate. The spec wins.

Fix. Declare the gate under gates (with text and disabled_status) or use the spec's variable name.

TG0609

macro dropped or its safety tier raised

Meaning. A macro could not be compiled as written: its name is also an operation id (the macro is dropped), or it declares a safety tier weaker than its strictest step (the macro gets the step's tier, because a macro can never be safer than what it calls).

Fix. Rename the macro, or declare a tier at least as strict as every call step.

TG0610

unknown x-agent- extension ignored*

Meaning. The spec uses an x-agent-* extension tungsten does not know, often a misspelling. It is ignored.

Fix. Fix the extension name (for example x-agent-safety), or rename it outside the x-agent- prefix if it is meant for another tool.

TG0611

x-agent- extension value is malformed; ignored*

Meaning. An x-agent-* extension of an operation has the wrong shape (for example x-agent-safety: dangerous or an x-agent-idempotency object without policy). The extension is ignored and the operation keeps its defaults or agent.yml rules.

Fix. Give the extension the shape of the matching agent.yml tools key (specs/agent-manifest.schema.json, ToolConfig).

TG0612

targets share or nest their output directories

Meaning. Two targets in tungsten.yml write to the same output directory, or one target's out is inside another's. Each target records its files in its own .tungsten/manifest.json and removes files it no longer generates, so targets sharing a directory delete each other's output on every run.

Fix. Give every target its own directory that is not inside another target's, for example typescript: { out: generated/typescript } and docs: { out: generated/docs }.

TG0613

agent.yml option not applied by this version; ignored

Meaning. agent.yml sets an option the schema accepts but this version of tungsten does not apply yet (disclosure.prune.drop_fields, disclosure.prune.keep_examples). Agent tool schemas describe exactly the arguments the SDK takes, so nothing is hidden and no examples are added; the rest of the manifest applies.

Fix. Remove the option, or keep it for a later version that applies it. To make a tool smaller now, shorten descriptions or raise defaults.disclosure.schema_budget_tokens.

TG0614

gates entry no operation is gated by

Meaning. A gates entry of agent.yml is used by no operation: the spec carries no x-runtime-gate for that environment variable and no tools entry names it in gate. The entry's text is never shown and a 404 from the routes it was written for is reported as NOT_FOUND ("check the identifiers") instead of GATE_DISABLED. Live runs against ZROtext showed it: SEALED_ADMISSION_ENABLED was declared but none of the sealed operations named it.

Fix. Add gate: <ENV_VAR> to the tools entry of every operation the deployment setting switches off (one entry per operation), or delete the gates entry.

Emitter limits (TG07xx)

TG0701

generated output could not be written

Meaning. A generated file could not be written to the target's output directory, for example because the directory is read-only or a path component is a file.

Fix. Check the target's out path and its permissions, then run tungsten generate again.

TG0702

target has no emitter in this version; skipped

Meaning. tungsten.yml configures a target (such as mock) for which this version of tungsten has no emitter yet. tungsten generate skips it and check --ci does not compare its output.

Fix. Nothing to fix. Remove the target from tungsten.yml to silence the notice, or generate it once a tungsten release ships its emitter.

TG0703

output directory was not generated by tungsten; refusing to write

Meaning. The target's output directory is not empty and has no .tungsten/manifest.json (or an unreadable one), so tungsten cannot tell its own files from yours. Writing would mix generated files into a directory it does not own, so nothing was written.

Fix. Point the target's out at a new or empty directory, or pass --force to write into it anyway; files tungsten did not generate are then left alone.

TG0704

output path leaves the output directory or is reserved

Meaning. A generated file would be written outside the target's output directory: a directory on its path is a symlink leading elsewhere, the file itself is a symlink, or the path is inside the reserved .tungsten/ directory. Nothing was written.

Fix. Remove the symlink from the output directory. If the path is under .tungsten/, the emitter is at fault: report it.

TG0710

macro not emitted by the TypeScript SDK (not in the canonical form)

Meaning. A macro in the IR does not fit the canonical form the TypeScript SDK compiles: a step names an operation that is not callable, a reference names a later or unknown step, or an {expr} is not <ref> in [..], <ref> == x or <ref> != x. The SDK is generated without that macro.

Fix. Fix the macro in agent.yml so every step calls a callable operation and every reference names $input or an earlier step's as.

TG0711

invalid TypeScript target option; default used

Meaning. An option of the typescript target is not valid (for example a package that is not an npm package name or a version that is not a semantic version), so its default is used.

Fix. Fix the option under targets.typescript in tungsten.yml.

TG0712

OpenID Connect scheme sent as a bearer token by the TypeScript SDK

Meaning. The API declares an OpenID Connect security scheme. The TypeScript SDK sends the configured credential as a bearer token and does not run discovery or obtain tokens itself.

Fix. Obtain the token with your OpenID Connect client and pass it in auth under the scheme's name.

TG0713

tool schema over the agent schema token budget

Meaning. A tool of tools.json (its name, description and parameters, measured as characters / 4 after repeated sub-schemas were moved to $defs) is larger than the per-tool schema budget of agent.yml (defaults.disclosure.schema_budget_tokens, 600 by default). Agents pay this cost every time the tool is listed.

Fix. Shorten the operation's and its fields' descriptions (disclosure.prune for the operation, the spec for fields), split the operation, or raise the budget.

TG0720

invalid MCP target option; default used

Meaning. An option of the mcp target is not valid (a package that is not an npm package name, a version that is not a semantic version, an sdk that is not <package> or <package>@<range>, an empty path or range, a sandbox that is not a boolean), so its default is used.

Fix. Fix the option under targets.mcp in tungsten.yml.

TG0721

MCP tool schema over the agent schema token budget

Meaning. An MCP tool (its description and input schema, measured with the tungsten-tokens estimate after repeated sub-schemas were moved to $defs) is larger than the per-tool schema budget of agent.yml (defaults.disclosure.schema_budget_tokens, 600 by default). Agents pay this cost whenever the tool is listed or described.

Fix. Shorten the operation's and its fields' descriptions (disclosure.prune for the operation, the spec for fields), split the operation, or raise the budget.

TG0722

progressive MCP tool list and index summary over the 2,000-token budget

Meaning. In progressive mode an MCP client first receives the meta tools (search_tools, describe_tool, invoke, preview, list_clusters) and the instructions with the cluster index. Together they exceed the 2,000-token budget of the progressive index, usually because of many clusters or long cluster summaries.

Fix. Shorten the cluster summaries in agent.yml (only their first sentence is used) or merge clusters.

TG0723

macro not exposed as an MCP tool (not emitted by the TypeScript SDK)

Meaning. A macro of the IR is not served by the MCP server because the generated TypeScript SDK, which runs it, does not emit it (see TG0710 of the typescript target).

Fix. Fix the macro in agent.yml so every step calls a callable operation and every reference names $input or an earlier step's as.

TG0724

MCP tool names collide; each is named with a digest of its operation

Meaning. Two or more operations or macros give the same MCP tool name once their namespace, resource path and method are reduced to [a-z0-9_] (/a-b/c and /a/b-c both become ..._a_b_c_get). Numbering them in IR order would hand a name to another operation when one of them is added or removed, so each is named with the first eight hex digits of the digest of its operation id or macro name instead (..._a_b_c_get_1f3e9a0c): stable, but not descriptive.

Fix. Give the operations distinct method names with naming.operations in tungsten.yml.

TG0725

disclosure.mode auto chose the MCP disclosure mode from the measured token size of the discrete tool list

Meaning. defaults.disclosure.mode: auto in agent.yml chooses between the discrete MCP tool list (every tool with its schema) and progressive disclosure (search_tools, describe_tool, invoke) by measuring the discrete tools/list plus its instructions with the tungsten token estimate. Progressive is chosen when that is above defaults.disclosure.list_budget_tokens (default 10000), whatever the number of tools. This note states the measured tokens, the budget and the decision.

Fix. Set defaults.disclosure.mode to discrete or progressive to decide yourself, or change defaults.disclosure.list_budget_tokens.

TG0726

the MCP server's SDK dependency defaults to the typescript target's package

Meaning. The mcp target has no sdk option, so the server depends on the package the typescript target of the same tungsten.yml generates (its package and version) instead of the default <api>-sdk.

Fix. Set targets.mcp.sdk (<package> or <package>@<range>) or targets.mcp.sdk_path to depend on something else.

TG0727

MCP tool output schema over the output token budget even without the types it references

Meaning. The output schema of an MCP tool is larger than four times the per-tool schema budget even though every reference to another type was already replaced by {} (the emitter keeps only the types one reference away from the response body, and none when that is still over the limit). The response type itself is large: many fields or long descriptions.

Fix. Shorten the descriptions in the spec, or raise defaults.disclosure.schema_budget_tokens in agent.yml.

TG0730

macro not emitted by the Python SDK (not in the canonical form)

Meaning. A macro in the IR does not fit the canonical form the Python SDK compiles: a step names an operation that is not callable, a reference names a later or unknown step, an {expr} is not <ref> in [..], <ref> == x or <ref> != x, or a field the macro adds to its input is not a free Python keyword argument name (not an identifier, a keyword, or an argument the extended operation already takes). The SDK is generated without that macro.

Fix. Fix the macro in agent.yml so every step calls a callable operation, every reference names $input or an earlier step's as, and added input fields have identifier names.

TG0731

invalid Python target option; default used

Meaning. An option of the python target is not valid (for example a package that is not a PEP 508 distribution name, a module that is not a lowercase identifier, a version that is not a PEP 440 version, or a models that is neither pydantic nor dataclasses), so its default is used.

Fix. Fix the option under targets.python in tungsten.yml.

TG0732

OpenID Connect scheme sent as a bearer token by the Python SDK

Meaning. The API declares an OpenID Connect security scheme. The Python SDK sends the configured credential as a bearer token and does not run discovery or obtain tokens itself.

Fix. Obtain the token with your OpenID Connect client and pass it in auth under the scheme's name.

TG0733

inline record typed as a plain mapping by the Python SDK

Meaning. A record schema without a name (inline, not a component) has fixed fields. The Python SDK declares a model class per named record only, so this one is typed dict[str, Any] and its fields are not validated client-side.

Fix. Move the schema to components/schemas (or name it with an overlay) so it gets a model.

TG0740

invalid Rust target option; default used

Meaning. An option of the rust target is not valid (for example a crate that is not a crate name, a version that is not semver, or a cli that is neither a boolean nor an object), so its default is used.

Fix. Fix the option under targets.rust in tungsten.yml.

TG0741

type or schema typed as serde_json::Value by the Rust SDK

Meaning. A schema has no Rust type of its own: a union without variants, an allOf that could not be merged into one record, a schema no value satisfies, or an inline enum, union or record without a name. The Rust SDK types it serde_json::Value (the generated type says so in its documentation) and checks its constraints (enum membership, allOf members) when the request or response is validated. Enums of booleans, of numbers with fractions and of integers above i64 are not in this group: they are untagged enums with one variant per JSON type, and enums of several types are unions of constants.

Fix. Move the schema to components/schemas (or name it with an overlay) so it gets a Rust type; for an allOf, make the members compatible so that they merge.

TG0742

macro not emitted by the Rust SDK (not in the canonical form)

Meaning. A macro in the IR does not fit the canonical form the Rust SDK compiles: a step names an operation that is not callable, a reference names a later or unknown step, an {expr} is not <ref> in [..], <ref> == x or <ref> != x, or the input extends an operation that is not callable. The SDK is generated without that macro.

Fix. Fix the macro in agent.yml so every step calls a callable operation and every reference names $input or an earlier step's as.

TG0743

OpenID Connect scheme sent as a bearer token by the Rust SDK

Meaning. The API declares an OpenID Connect security scheme. The Rust SDK sends the configured credential as a bearer token and does not run discovery or obtain tokens itself.

Fix. Obtain the token with your OpenID Connect client and pass it in auth under the scheme's name.

TG0744

operation with different non-JSON or ranged success bodies returns serde_json::Value in the Rust SDK

Meaning. An operation's success responses have different bodies, and they are not all JSON bodies under exact statuses (a body is text, binary or a form, or a status is a range such as 2XX). The Rust SDK types an operation whose exact statuses answer with different JSON bodies as a response enum; for the shapes it cannot represent it returns serde_json::Value and does not validate the response.

Fix. Declare each success status exactly and describe its body as JSON, or call the operation through Dispatch::invoke, which returns JSON.

TG0745

tagged union emitted by the Rust SDK as an untagged one

Meaning. A union has a discriminator, but a variant has no tag value: the mapping does not name it and it is not a component with a name or a constant to take the tag from. A union whose variants all have tags is decoded by the tag, whatever the variants are (records, other unions, maps), like the TypeScript and Python SDKs; this one cannot be, so the Rust SDK tries its variants in order like an untagged union.

Fix. Name every variant under the discriminator's mapping, or give every variant a component of its own.

TG0746

macro output typed as serde_json::Value by the Rust SDK

Meaning. The output of a macro is not an object or a reference whose members the Rust SDK can type: a member is a null, a list, a nested object or a reference into a step the API description gives no single JSON response type for. The macro's method returns serde_json::Value, the output expression evaluated by the runtime.

Fix. Read the members you need from the value, or flatten the output expression to references into steps with a documented response ($step.field) and boolean expressions.

TG0750

argument given as JSON text on the command line of the generated CLI

Meaning. An argument of an operation has no plain flag form in the generated CLI: a parameter whose type is an object, a map, a union or a list of those, or a multipart body whose parts are files. An object, map or union takes JSON text (--filter '{"a":1}', --filter @filter.json or - for standard input) or its members one at a time (--filter.a 1, --filter.created.after 5; a value is typed by the operation's schema, and both forms can be mixed, the members applied on top of the JSON text). A list of those repeats the flag, one JSON value each. A multipart file cannot be given from the command line at all.

Fix. Use the JSON or dotted form, or the SDK for multipart uploads. Nested fields of a request body are JSON-text flags by design and are not reported.

TG0751

resource named like a command of the generated CLI; renamed

Meaning. A resource, or a namespace, has the name of a command the generated CLI provides itself (auth, help, operations, schema). Its commands are under <name>-resource so that both exist.

Fix. Rename the resource under resources in tungsten.yml.

TG0752

flag renamed in the generated CLI because its name is taken

Meaning. The flag derived from an argument has the name of a flag the CLI adds to every command (--json, --body, --yes, --dry-run, --idempotency-key, --timeout, ...) or of another flag of the same command. The argument keeps its name in the SDK; its flag gets the suffix -arg.

Fix. Use the renamed flag, or rename the parameter in the spec or an overlay.

TG0753

two commands of the generated CLI share a path; the later one is numbered

Meaning. Two operations or macros end up with the same command path in the generated CLI (an operation and a macro with the same name, or a resource renamed onto another). The later one gets a numeric suffix so that both stay reachable.

Fix. Give the operations distinct names with naming.operations in tungsten.yml.

TG0760

types no operation reaches were not generated (types.prune_unreferenced)

Meaning. Some components/schemas entries are not reachable from any operation (typically the schemas only the operations excluded by an include predicate use), so they were not generated: no type, no validator, and none of the warnings their schemas would have raised. The note counts them and lists the first names. Operations that are only planned (planned_from) and the error envelope still keep the types they use.

Fix. Nothing to fix. To generate every schema anyway, set types.prune_unreferenced: false in tungsten.yml.

TG0790

invalid WebMCP target option; default used

Meaning. An option of the webmcp target is invalid, such as a malformed npm package, SDK dependency, runtime dependency or version. The emitter uses its documented default for that option.

Fix. Fix the option under targets.webmcp in tungsten.yml.

TG0791

WebMCP generated file could not be added

Meaning. The WebMCP emitter could not add a generated file to its output. The diagnostic identifies the file and the reason.

Fix. Check the target configuration. If the generated path is invalid or duplicated, report an emitter bug.

TG0792

WebMCP SDK dependency defaults to the TypeScript target package

Meaning. The webmcp target has no explicit SDK dependency, so the browser adapter depends on the package and version the typescript target generates.

Fix. Generate and make that TypeScript package available, or set targets.webmcp.sdk (<package> or <package>@<range>) or targets.webmcp.sdk_path.

TG0793

WebMCP preview tool name collides with an invocation tool

Meaning. A confirmation-bearing WebMCP tool's generated __preview name is already used by another invocation tool. The browser runtime rejects a registration whose selected tools contain that collision.

Fix. Rename the colliding operation or macro so invocation and preview tool names are distinct.

External emitters (TG08xx)

TG0801

external emitter not found or cannot be started

Meaning. A target in tungsten.yml declares external, but its emitter could not be run: with external: true there is no executable tungsten-emit-<name> on PATH; with a command, its program does not exist, is not executable, or the operating system refused to start it. Nothing is generated for the target.

Fix. Install the emitter and put it on PATH, or point external at it (a path with a slash is relative to tungsten.yml, a bare name is looked up on PATH). tungsten emitters lists what tungsten finds.

TG0802

external emitter speaks a different protocol version

Meaning. The external emitter answered with a protocol version other than 1, the only version this tungsten speaks. The response is not read.

Fix. Use an emitter release built for protocol 1, or a tungsten release that speaks the emitter's protocol. tungsten emitters shows the protocol each emitter reports.

TG0803

external emitter failed: non-zero exit, timeout or output over the cap

Meaning. The external emitter ran but did not finish normally: it exited with a non-zero status or was killed by a signal (the end of its standard error is quoted), it did not finish within timeout_ms (default 60 s), or it wrote more than max_output_bytes (default 64 MiB) to standard output. Nothing is generated for the target.

Fix. Run the emitter by hand with a request on its standard input to see why it fails. Raise timeout_ms or max_output_bytes on the target if the limit is too tight for a large API.

TG0804

external emitter returned an invalid response

Meaning. The external emitter's standard output is not a valid response of protocol 1: it is not JSON, a field has the wrong type, a file has both or neither of content and content_base64, a base64 value is malformed, a path is listed twice, or there are more than 10000 files. The same code reports a --describe document that is not valid. Nothing is generated for the target.

Fix. Check the emitter against the schema printed by tungsten schema external-emitter (validate the response against #/$defs/EmitResponse).

TG0805

external emitter returned a path outside the output directory

Meaning. The external emitter named a file path that is absolute, has a .., . or empty segment, a backslash, a NUL byte or a drive prefix, or starts with .tungsten/. Generated files are written only inside the target's out directory, so the whole response is refused and nothing is written.

Fix. Make the emitter return paths relative to the output directory with / separators. It never needs the absolute output path.

TG0806

diagnostic reported by an external emitter

Meaning. A diagnostic reported by an external emitter, kept with its severity. The message reads external emitter <name>: <code>: <text>, where <code> is the emitter's own code. An error fails the target; under --strict a warning does too.

Fix. Fix the cause the emitter describes; tungsten explain knows only tungsten's own codes, so look the emitter's code up in the emitter's documentation.

Staleness and CI (TG09xx)

TG0901

generated output is stale relative to its inputs

Meaning. A target's output directory differs from what tungsten generate would write now: a generated file is missing or has other content, a file of the previous generation would be removed, or .tungsten/manifest.json is missing. Usually the spec or a manifest changed after the last generation, or a generated file was edited by hand.

Fix. Run tungsten generate and commit the result. Put hand-written code in the target's custom/ files, which generation never overwrites.

TG0902

API surface snapshot of the last generation is missing or unreadable; the change is not classified

Meaning. tungsten diff --semver and tungsten report compare the API surface recorded by the last generation (.tungsten/surface.json in the target's output directory) with the current one. The target has no snapshot (it was never generated, or generated by a tungsten that did not record one), or the snapshot cannot be read or parsed, so the change since that generation is not classified as major, minor or patch.

Fix. Run tungsten generate to record a snapshot; later runs of tungsten diff --semver classify the changes made after it. Do not edit files under .tungsten/.

TG0920

overlay suggest: a diagnostic has an overlay fix but its value cannot be derived; skipped

Meaning. tungsten overlay suggest found a diagnostic that an overlay action could fix, but the value the action needs cannot be derived without guessing: the operation has no single id in the IR (its document is shared by several namespaces, or the operation is expanded from an rpc envelope), or its position cannot be written as an Overlay target. The overlay suggestion leaves it out; it never writes placeholder text.

Fix. Fix the diagnostic by hand in the spec (add or change the operationId), or in the overlay you maintain yourself.

TG0921

overlay suggest: no overlay action can fix this diagnostic code

Meaning. tungsten overlay suggest only writes actions whose fix the compiler has already decided: the id of an operation without operationId, and the unique id of an operation whose operationId is used more than once. Warnings of any other code, such as an inferred pagination (TG0501) or a renamed field or type (TG0401), need a decision or live in tungsten.yml; the count is reported once per code.

Fix. Use tungsten explain on the code for its usual fix, for example declare the pagination under pagination in tungsten.yml.