Generator diagnostics

• 💀 Fatal: An issue that prevents code generation entirely.
• ❌ Error: Undesired or unexpected behavior. Resolve all errors before a 0.0.1 release.
• ⚠️ Warning: Potentially undesired or unexpected behavior. Resolve all warnings before a 1.0.0 release.
• ✍️ Note: A potential improvement or misconfiguration. Investigate all notes before a 1.0.0 release.

API

❌ API/AppNotAuthorized

GitHub App not authorized.

{message}

Try authorizing the Stainless GitHub app again.

CLI

⚠️ CLI/UnsupportedMethodType

Only HTTP methods are supported by the CLI generator, so this method will be omitted.

⚠️ CLI/UnsupportedCookie

The CLI generator does not currently support passing cookie parameters, so this method will be omitted.

⚠️ CLI/UnsupportedContentType

The CLI generator does not currently support the content type '{content_type}', so this method will be omitted.

CSharp

✍️ CSharp/CollapsedUnionHasRedundantModel

This union collapses to its enum variant ({collapsed_variant.stainless_path}), but both are models, so only the enum model will be respected.

Only define either the union or the enum variant as a model.

✍️ CSharp/SchemaUnionDiscriminatorMissing

This union schema has more than one object variant, but no discriminator property, so deserializing the union may be inefficient or ambiguous.

Deserializing this union schema requires trying to match it against each object variant in sequence, which may:

• Be inefficient for large or many variants
• Result in ambiguities if two object variants have the same required properties

Adding a discriminator property solves these problems because it immediately indicates which variant a serialized union should be deserialized to.

If these problems don't apply to this union schema, the ignore this note. Otherwise, add a discriminator property.

ClientOpt

⚠️ ClientOpt/UnnecessarilyRequired

Unnecessarily required security config option {client_opt_name}.

{client_opt_name} is non-nullable, but isn't used in every security config, so it will be unnecessarily required in some cases.

Set nullable: true on the option or use it in every security config .

⚠️ ClientOpt/NotFound

Ignored unknown client option {client_opt_name}.

Use the name of a valid option in client_settings.opts or set client_settings.opts.{client_opt_name} to a valid value.

Config

❌ Config/OpenAPIReferenceInvalid

{reason}

❌ Config/UnknownEdition

Unknown edition '{edition}'. Known editions: '{known_editions.0}', '{known_editions.1}'

✍️ Config/Deprecated

{old_key} has been renamed to {new_key}, will be rejected in future releases

{detail}

Endpoint

❌ Endpoint/NotHttp

Skipped invalid endpoint: {endpoint}

Stainless only supports valid HTTP endpoints with the following characteristics:

• Starts with an HTTP method (get, post, put, patch, delete or query)
• The method is followed by a single space
• The single space is followed by a path that begins with /
• The method contains no wildcards or placeholders

Example valid path: get /api/customers

❌ Endpoint/NotFound

Skipped endpoint because it's not in your OpenAPI spec: {endpoint}

Verify this endpoint is correctly named in your Stainless config, confirm you've uploaded the correct OpenAPI spec, or add this endpoint to your OpenAPI spec if needed.

Code will not be generated for this endpoint until this issue is resolved.

❌ Endpoint/NotSpecified

{endpoint} is in unspecified_endpoints, so code will not be generated for it.

❌ Endpoint/BothSpecifiedAndUnspecified

{endpoint} is in unspecified_endpoints, but is specified in resources, so code will still be generated for it.

An endpoint cannot be both specified and unspecified. Remove it from unspecified_endpoints or resources.

✍️ Endpoint/NotConfigured

Skipped endpoint because it's not in your Stainless config: {endpoint}

This endpoint is in your OpenAPI spec, but not present in the resources section of your Stainless config. We only generate code for endpoints present in both your OpenAPI spec and Stainless config.

✍️ Endpoint/IsIgnored

{endpoint} is in unspecified_endpoints, so code will not be generated for it.

If this is intentional, then ignore this note. Otherwise, remove the endpoint from unspecified_endpoints and add it to resources.

Environment

❌ Environment/InvalidURL

Invalid URL template {url_template} in environment {environment_name}.

Your URL template must include a protocol (https://), a valid domain. If you use template variables, they must exist and their values must produce valid URLs when combined with your URL template.

✍️ Environment/ProtocolRelativeURL

The {environment_name} environment's URL ({url_template}) is protocol-relative, so it will be assumed to support {assumed_protocol} ({replacement_url_template}).

Go

❌ Go/DuplicateVariantNameForUnion

Overlapping variant names for union: {type_name}

We were unable to infer unique names for this union.

These schemas overlap:

• {variants.0}
• {variants.1}

Assign new names to these schemas using transforms, make these variants a model, or modify your OpenAPI spec to resolve the name issues.

❌ Go/SnippetNotValid

Invalid example code snippet.

We were unable to format this example code:

{snippet}

stdout:

{stdout.contents}

stderr:

{stderr.contents}

⚠️ Go/AddedParamsSuffix

The param type for ModelRawName was renamed to ModelRawNameParam.

In the Go SDK {model.raw_name} will be generated twice, once as a param type, and once as a response type. Because of the targets.go.options.remove_params_suffix: true option, the params name will be called ModelRawNameParam.

If a previous release had {model.raw_name} in responses only, or didn't have it at all, ignore this diagnostic.

If a previous release had {model.raw_name} only as a param, annotate the model's OpenAPI Schema with x-stainless-go-rename-response-model: true.

⚠️ Go/SchemaVariantRequiresDiscriminator

Variant for union requires a property for discriminator {discriminator_property_name}

⚠️ Go/SchemaVariantTypeNotSupported

Variant type '{variant_type}' is not currently supported

✍️ Go/MultipleFormatsInUnion

Multiple different schema formats found for variants of {oas_path}: {formats.0}, {formats.1}

✍️ Go/DuplicateVariantDeserializationConditions

This union schema has more than one variant with the same deserialization condition, so some of the variants may never be deserialized to.

The following variants have the same deserialization condition:

{conditions.0.representation}: gjson={conditions.0.gjson_value} discriminatorValue={conditions.0.discriminator_value}
{conditions.1.representation}: gjson={conditions.1.gjson_value} discriminatorValue={conditions.1.discriminator_value}

Update these variants so that they can be differentiated during deserialization or remove all but one of them.

✍️ Go/SchemaUnionDiscriminatorMissing

Union has object variants but no discriminator.

Deserialization may be inefficient or ambiguous without a discriminator because each object variant must be tried in sequence.

Add a discriminator property to the union schema so the correct variant is identified immediately.

✍️ Go/NameNotAllowed

{reason}

Java

❌ Java/UnsupportedAliasModel

We currently do not support generating alias models in Java/Kotlin. You will have to remove it from the config.

⚠️ Java/NameIsReserved

This schema has a name that conflicts with a reserved name, so it will be renamed from {name} to {new_name}.

Set a different name by doing one of:

• Defining a model
• Setting a title property on the schema
• Extracting the schema to #/components/schemas

⚠️ Java/NestedAndParentClassNamesConflict

This schema's class has the same name as one of its parent classes, so it will be renamed from {class_name} to {new_class_name}.

Set a different name by doing one of:

• Defining a model

• Setting a title property on the schema

• Extracting the schema to #/components/schemas

• Setting an x-stainless-naming property on the schema like so:

  x-stainless-naming:
    java:
      type_name: NewClassName
  

✍️ Java/NameNotAllowed

{reason}

Use a model or title property to set an explicit Java name.

✍️ Java/SchemaUnionDiscriminatorMissing

Union has object variants but no discriminator.

Deserialization may be inefficient or ambiguous without a discriminator because each object variant must be tried in sequence.

Add a discriminator property to the union schema so the correct variant is identified immediately.

✍️ Java/CollapsedUnionHasRedundantModel

This union collapses to its enum variant ({collapsed_variant.stainless_path}), but both are models, so only the enum model will be respected.

Only define either the union or the enum variant as a model.

MCP

❌ MCP/NoToolsEnabled

All MCP tools are set to false, at least one must be enabled.

You have manually disabled all of the MCP tools in your MCP server configuration, which means your server will generate with no capabilities.

To fix, either disable your MCP server, or enable the docs search tool or the code tool with:

enable_docs_tool: true

or

enable_code_tool: true

in your Stainless Config MCP server settings.

Method

❌ Method/InvalidBinaryUpload

Invalid file upload endpoint.

File upload endpoints with content type {content_type} must have a single body parameter ({num_body_params} were found for this endpoint) and the file parameter schema must have type set to string and format set to binary.

❌ Method/NameNotValid

Method {method_name} has an invalid name.

{reason}. Rename the method to avoid conflicts.

❌ Method/XStainlessInvalid

The x-stainless-method config is invalid.

{error}

⚠️ Method/MatchedMultiplePages

Ignored duplicate pagination scheme for method {endpoint}.

The following pagination schemes matched: {pages.0} and {pages.1}.

Add an explicit pagination: {page_name} to the method definition to disambiguate.

⚠️ Method/PaginatedWithoutMatchingScheme

Skipped pagination for method {endpoint} (no matching pagination scheme).

The method is paginated because its name starts with list or its paginated property is set to true in the Stainless config.

If this is intentional, then add a pagination scheme for the method. Otherwise, remove its paginated property from the Stainless config or set its paginated property to false if the method's name starts with list.

The following defined pagination schemes have issues:

• {results.0.page}:
  • {results.0.errors.0}
  • {results.0.errors.1}
• {results.1.page}:
  • {results.1.errors.0}
  • {results.1.errors.1}

⚠️ Method/ExpectedMatchPaginationScheme

Skipped pagination for method {endpoint} (scheme {pagination_scheme} did not match).

Reasons why matching {result.page} failed:

• result.errors.0
• result.errors.1

There were matches of these other pagination styles: {other_matches.0} and {other_matches.1}

⚠️ Method/ExpectedNoPagination

Skipped pagination for method {endpoint} (unexpectedly matched scheme).

These pagination styles: "" matched because {reason}.

If the endpoint is paginated, you can disable this diagnostic by setting paginated to true in the method config.

Example:

methods:
  my_method:
    type: http
    endpoint: get /examples
    paginated: true

By default Stainless expects methods for paginated endpoints to be prefixed with list. That's a simple and common convention that helps users understand that the method is paginated.

If you have a use case for a paginated method that doesn't follow that convention, you can disable this diagnostic by setting paginated to true in the method config.

methods:
  my_method:
    type: http
    endpoint: get /examples
    paginated: true

⚠️ Method/MissingEnvelopeUnwrap

Disabled envelope unwrapping for method {endpoint} (missing unwrap property {unwrap_field}).

The following fields were found on the response object: {existing_properties.0} and {existing_properties.1}.

If this endpoint intentionally doesn't match a response envelope, you can disable matching for this endpoint by configuring the method at {config_path} to have unwrap_field: false

⚠️ Method/AmbiguousEnvelopeUnwrap

Disabled envelope unwrapping because multiple properties matched.

The following properties matched: {matched_properties.0} and {matched_properties.1}.

Disambiguate by setting a specific unwrap property, e.g. unwrap_response: {matched_properties.0} on the method config.

⚠️ Method/PathNotValid

Skipped method because path {path} did not start with /.

Ensure the method's path starts with /.

⚠️ Method/RequestBodyNotSupported

GET endpoint {endpoint} has a request body

This is usually a mistake in the spec, and can be resolved by removing the request body from the endpoint.

If this is how your API works, we suggest you change your API, as some javascript runtimes do not support this, and neither does the Go standard library.

⚠️ Method/XStainlessDuplicate

Skipped duplicate x-stainless-method for endpoint {new_endpoint}.

{method_path} is assigned to endpoint {existing_endpoint}, but endpoint {new_endpoint} also tried to use it.

Each x-stainless-method value must be unique. Either rename one of the methods or remove the duplicate annotation.

⚠️ Method/XStainlessAlreadyConfigured

Ignored x-stainless-method annotation (method was already configured).

Endpoint {endpoint} has x-stainless-method: {method_path}, but this method is already configured in the Stainless config.

Remove either this x-stainless-method annotation or the corresponding methods config entry.

⚠️ Method/XStainlessInvalidSyntax

Ignored endpoint {endpoint} with invalid x-stainless-method format.

Got x-stainless-method: {value}. This value must be a dotted string in the format resource.method, e.g. "users.list" or "accounts.users.create".

✍️ Method/OptionalBinaryRequestBody

Made binary upload body required (was optional).

Binary file upload endpoints always require a request body. Your OpenAPI spec marked this endpoint's body as optional, but we ignored that directive.

To silence this note, remove the optional body declaration on this endpoint.

✍️ Method/PathHasRepeatedComponent

This endpoint has duplicate path component {component} in the path {endpoint}, which may not be intended.

✍️ Method/BodyRootParamUnnamed

Confirm {fallback_name} is an appropriate name for this method's request parameters.

This method has a non-object request body, so we generated the fallback name {fallback_name} for it.

If {fallback_name} is an appropriate name for this method's request parameters, ignore this note.

If {fallback_name} is not an appropriate name, define a different name for this method's request parameters with body_param_name in your Stainless config.

✍️ Method/DefinesBaseURLWithMultipleEnvironments

{endpoint} defines an alternate server URL {url}, but the config defines more than one environment. Requests will always be sent to this alternate server URL, regardless of environment.

Model

❌ Model/NotFound

Missing path was ignored: {path}

This path is not present in your Stainless config, so we ignored it.

To resolve this error, add this path to your Stainless config or remove the path from your OpenAPI spec.

❌ Model/GeneratedNameClash

Name clash may cause compile errors.

The same name, {generated_name}, has been generated for {new_schema_ref} and {previous_schema_ref}. This issue will likely prevent your Go SDK from compiling.

To fix this issue, explicitly give one or both of these a unique name using a model in your Stainless config.

❌ Model/DuplicateName

Skipped model because name already exists: {existing_model_name}

Models must have a unique name or a unique namespaced name under a resource with standalone_api set to true.

❌ Model/XStainlessInvalid

The x-stainless-model config is invalid.

{error}

⚠️ Model/XStainlessInvalidSyntax

Invalid x-stainless-model format: {value}.

The value must be a dotted string in the format resource.model, e.g. "users.profile" or "accounts.users.user".

⚠️ Model/ParamsSuffixNameClash

Ignored no_params_suffix because it would cause a name clash.

The schema is used in a response, so removing the params suffix would clash with the response type name. Remove no_params_suffix: true or rename one of the models.

⚠️ Model/DuplicateDefinition

Ignored duplicate model for schema {ref_name}.

This schema is already declared as a model at {existing_model_name}. Remove one of the duplicate model definitions.

✍️ Model/IsConstant

This schema has only one possible value, but it's a model, so it won't be automatically set as the default value for the user.

If the schema may have more possible values in the future, then ignore this note. Otherwise, don't define it as a model. Some SDKs conveniently set constant non-model schemas as the default for the user.

This schema's only possible value is the following:

"{constant}"

✍️ Model/Recommended

We recommend you use a model for {oas_path}

This schema will be duplicated in your generated code, even if its definition uses a shared $ref. To avoid this, we recommend you define this schema as a model.

✍️ Model/NeedsRename

Consider renaming model {model.raw_name}; e.g. {suggestion}'

✍️ Model/IsIndirect

{config_path} references a schema that has $ref: {schema_ref}, but could potentially reference {schema_ref} directly.

If this is for naming or other purposes, then ignore this note. Otherwise, consider referencing {schema_ref} directly for clarity.

Name

⚠️ Name/Collision

Possible undesirable name generated for {language}

We tried to use preferred names in {language}, but due to language constraints we had to use {fallback_name} instead. Here are the names we tried to use and why we couldn't use them:

These preferred names were tried in order, but could not be used for the following reasons:

1. {renamings.0.preferred_name} {renamings.0.reason} ({renamings.0.conflicting_name_location})
2. {renamings.1.preferred_name} {renamings.1.reason} ({renamings.1.conflicting_name_location})

These preferred names were made up of other names:

• diagrams.0
• diagrams.1

If {fallback_name} is appropriate, ignore this diagnostic.

If you want to use a different name, use x-stainless-naming or another transform to define your preferred name.

✍️ Name/NotSnakeCase

{name} is not in snake_case format. Consider renaming to {snake_case_name}.

✍️ Name/Renamed

2 names were renamed due to {language} constraints, so fallback names will be used instead.

The following fallback names will be used:

• {renamings.0.fallback_name} ({renamings.0.location})

  These preferred names were tried in order, but could not be used for the following reasons:

  1. {renamings.0.renamings.0.preferred_name} {renamings.0.renamings.0.reason} ({renamings.0.renamings.0.conflicting_name_location})
  2. {renamings.0.renamings.1.preferred_name} {renamings.0.renamings.1.reason} ({renamings.0.renamings.1.conflicting_name_location})

  These preferred names were made up of other names:

  • renamings.0.diagrams.0
  • renamings.0.diagrams.1

• {renamings.1.fallback_name} ({renamings.1.location})

  These preferred names were tried in order, but could not be used for the following reasons:

  1. {renamings.1.renamings.0.preferred_name} {renamings.1.renamings.0.reason} ({renamings.1.renamings.0.conflicting_name_location})
  2. {renamings.1.renamings.1.preferred_name} {renamings.1.renamings.1.reason} ({renamings.1.renamings.1.conflicting_name_location})

  These preferred names were made up of other names:

  • renamings.1.diagrams.0
  • renamings.1.diagrams.1

OAS

❌ OAS/ReferenceNotFound

The {missing_pointer} reference isn't in your spec.

Your spec references {missing_pointer} from {ref_location}, but {missing_pointer} doesn't exist in your spec.

Check for a typo in the $ref path, add the missing schema definition, or adjust your spec to resolve the missing reference.

❌ OAS/NotValid

Invalid OpenAPI spec content at {oas_path}

{reason}

Fix the schema at this path and try again. Reference the OpenAPI specification if needed.

✍️ OAS/InvalidExample

Example is not valid for schema

Example: "{value}"

{reason}

✍️ OAS/InvalidUnionExample

Could not find matching variant for the given example "{example}"

✍️ OAS/InvalidDefault

This default is not valid for the schema, so the default will be ignored.

The invalid default value:

"{default}"

Operation

⚠️ Operation/PathTemplateVariableMissingParameter

This operation is missing a path parameter for its {{name}} path template variable.

Define a parameter named {name} for this operation.

Pagination

❌ Pagination/MissingProperty

Could not infer a response property with a '{purpose}' purpose as there were 2 applicable properties {inferred_schemas.0.schema_ref.property_info.api_name} and {inferred_schemas.1.schema_ref.property_info.api_name}.

Explicitly declare which response property to use {used_for}. For example:

{in}:
  {example}

❌ Pagination/UnsupportedPurposePlacement

Explicit pagination purpose '{purpose}' can only be set for schemas within object properties but it was set on a schema with a {schema.parent.type} parent.

❌ Pagination/UnsupportedItemsSchemaType

The paginated items schema must be an 'array' type, received '{schema.type}'.

❌ Pagination/UnusedPurposeConfig

Pagination purpose is unused.

Confirm this pagination purpose is valid for {page.type}. See our pagination documentation for more details.

❌ Pagination/DuplicatePurpose

Pagination purpose '{purpose}' should only be defined once but it was defined {amount} times.

❌ Pagination/ExpectedItemsToBeObject

Paginated items schema must be object type.

❌ Pagination/ExpectedHasNextPageToBeBoolean

Expected paginated response field {property_name} to be a boolean type.

⚠️ Pagination/DuplicateName

Ignored duplicate pagination configs named {name}.

These pagination configs conflict with each other:

pagination:
  {indices.0}: { name: {name}, … }
  {indices.1}: { name: {name}, … }

✍️ Pagination/NotConfigured

Confirm your API does not return paginated results.

Your Stainless config doesn't contain pagination information.

If your API returns paginated results, add one or more pagination schemes to your Stainless config. See our pagination guide for more details.

If your API does not return paginated results, ignore this note.

Parameter

❌ Parameter/SchemaTypeNotValid

Path parameter has unsupported type {type}.

Expected one of {supported_types.0} or {supported_types.1}.

❌ Parameter/MissingBrackets

This array query parameter's name doesn't end with [], but other array query parameters' names do.

Mixing brackets and non-brackets syntax is not supported. Use consistent array query parameter names throughout your spec.

⚠️ Parameter/NotFound

Ignored unknown param {path} in positional_params.

Remove {path} from positional_params, or add it to the endpoint's parameters.

⚠️ Parameter/NotValid

{reason}

⚠️ Parameter/DuplicateNames

Duplicate parameters were renamed: {name}

Multiple parameters have the same identifier, so we were forced to rename them.

Rename the following parameters using x-stainless-param:

• {params.0.oas_ref}
• {params.1.oas_ref}

For example:

name: {params.0.property_info.sdk_name}
in: {params.0.param_location}
# ...
x-stainless-param: other_{name}

⚠️ Parameter/ShadowedName

Excluded parameter {name} because it was shadowed by {name}[].

Change the type of the shadowed parameter to match the corresponding array, or remove it entirely.

⚠️ Parameter/BracketsFormatNotSet

This array query parameter's name ends with [], but brackets format is not set.

Configure query_settings.array_format: brackets in the Stainless config to support brackets.

⚠️ Parameter/MissingName

Ignored parameter with missing name.

Add a non-empty name property to this parameter.

⚠️ Parameter/MissingSchema

Defaulted parameter to type: string because no schema was defined.

Define an explicit schema for this parameter.

⚠️ Parameter/InvalidLocation

Ignored parameter with invalid location {location}.

The in property must be one of path, query, header, or cookie.

⚠️ Parameter/Duplicate

Ignored duplicate {location} parameter {name}.

Multiple parameters with the same name and location are not allowed. Only the first one will be used. Remove the duplicate parameter definitions.

✍️ Parameter/NameHasBrackets

Parameter has supplied name {parameter_name}, the trailing [] was stripped for the SDK parameter name.

✍️ Parameter/PathIsOptional

This path parameter has required: false, which is unsupported, so it will not be interpreted as optional.

✍️ Parameter/PathIsNullable

This path parameter has type: null or nullable: true, which is unsupported, so it will not be interpreted as nullable.

✍️ Parameter/PathTemplateVariableMissing

This path parameter has no corresponding template variable, so it will be ignored.

Remove it or add {{name}} template variable to the path.

✍️ Parameter/HeaderIsNullable

This header parameter has type: null or nullable: true, which is unsupported, so it will not be interpreted as nullable.

A header parameter can be optionally sent, which is configured by the required property, but it cannot be sent as null.

Make the header parameter optional and non-nullable instead.

Path

✍️ Path/RepeatedTemplateVariable

This path repeats {{name}}, which is likely not intentional.

Php

✍️ Php/UnnamedType

The PHP SDK generator is not yet able to pick a meaningful name for this type, will use {generated_name} for now

Python

❌ Python/PackageNameNotAllowed

Invalid Python package name: {package_name}

Python doesn't allow the following characters in package/import names: -, @ and /. We replaced those characters with underscores (_).

We recommend you provide explicit project_name and package_name values in your Stainless config instead of relying on our name correction behavior.

❌ Python/RequestParamShadowsDefault

Renamed param {name} because it shadowed a request option.

{name} was renamed to api_{name}. The Python generator reserves extra_headers, extra_query, extra_body, timeout, and idempotency_key as request options.

To use a custom name, set x-stainless-param on the parameter's schema in your OpenAPI spec:

schema:
  x-stainless-param: api_{name}

⚠️ Python/PyPiPackageNameDeprecated

targets.python.publish.pypi.package_name is deprecated, please remove it in favour of targets.python.project_name

⚠️ Python/PublishingWithoutOIDC

Publishing security issue: trusted publishing with OIDC is not enabled.

You have publishing configured, but you haven't enabled trusted publishing with OIDC. We recommend you enable trusted publishing.

OIDC eliminates the security risks associated with long-lived write tokens, which can be compromised, accidentally exposed in logs, or require manual rotation.

With OIDC trusted publishing, each publish uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.

⚠️ Python/DuplicateDeclaration

Multiple types generated with the same name {typename}.

If these types are the same, extract them to a shared $ref in your OpenAPI spec and declare it as a model. If they are different, rename one using x-stainless-naming:

x-stainless-naming:
  python:
    type_name: UniqueTypeName

✍️ Python/NameNotAllowed

{reason}

Use x-stainless-naming to set an explicit Python name, or rename in your OpenAPI spec.

Readme

⚠️ Readme/MissingStreamingSnippet

Streaming has been configured but there is no readme.example_requests.streaming snippet defined

⚠️ Readme/MissingPaginationSnippet

Pagination is enabled, but your readme is missing an example.

Add a readme.example_requests.pagination entry to your Stainless config that references one of your paginated endpoints. For example:

readme:
  example_requests:
    pagination:
      type: request
      endpoint: get /my_resource
      params: {}

ReadmeExample

❌ ReadmeExample/CustomConfigNotValid

run_check_in_path set to true but no path given - {check}

⚠️ ReadmeExample/MethodNotPaginated

Expected method {method.name} to be paginated

⚠️ ReadmeExample/MethodNotStreaming

Expected method {method.name} to be streamed

⚠️ ReadmeExample/MissingNestedParam

Expected the given example params to include a nested object but couldn't find one. Try using the `` endpoint with nested parameter {suggestion.key}.

✍️ ReadmeExample/MissingParam

Example is missing required parameter {key}.

Add {key} to the params of this example under readme.example_requests in your Stainless config to ensure this example runs correctly.

✍️ ReadmeExample/InvalidParameter

Value provided for parameter {parameter} doesn't match its schema.

The following value was provided:

"{val}"

✍️ ReadmeExample/ReadOnlyProperty

A value was provided for read-only property {prop}, but requests shouldn't include read-only properties.

The following value was provided:

"{val}"

✍️ ReadmeExample/UnknownProperty

Example supplied parameter {extra_param} which does not exist for method {method.name}.

✍️ ReadmeExample/UnknownResponseProperty

Response property {response_property} is not defined on the response for method {method.name}.

Reference

❌ Reference/NotFound

Missing reference: {ref}

We ignored this reference, so your generated code is probably missing features or functionality.

Make sure there are no typos in the reference path, or add the missing schema definition to your OpenAPI spec. It's also possible you meant to reference {closest_ref}.

❌ Reference/NotASchema

{path} resolved to a value that doesn't look like a schema: "{value}".

Resource

❌ Resource/NotFound

Resource not found in Stainless config: {path}

Resources not found in your Stainless config were ignored.

❌ Resource/HasEmptyName

Resource at {path} has an empty or whitespace-only name, which is not allowed.

The resource has been automatically renamed to {fallback_name}.

❌ Resource/HasConflict

Name conflict detected which may cause errors.

The following names conflict with each other:

• {paths.0}
• {paths.1}

Merge these resources to resolve this issue.

Response

❌ Response/TypeNotObjectForEnvelope

unwrap_response_fields has been set but the method's response type is {response_type} not object.

Envelope unwrapping only supports top-level response schemas with type: object and type: allOf. You may want to re-define the response schema, or turn off response unwrapping for this method by setting unwrap_response to false.

❌ Response/UnsupportedHeaderType

Unexpected non-primitive type: {type} for response header schema: {name}

✍️ Response/UnsupportedContentType

Unsupported response content type: {content_types.0} and {content_types.1}.

Stainless supports JSON (application/json), text (text/plain), and binary (application/octet-stream) content types for API responses. Endpoints that provide responses with other Content-Type values may not work as expected.

✍️ Response/SchemaTypeNotValidForText

Expected schema with type: 'string' for content type {content_type}

Ruby

❌ Ruby/PaginationTypeUnsupported

The Ruby SDK generator does not yet support {type} pagination

❌ Ruby/UnexpectedParams

Unable to generate a method corresponding to the params in this method

⚠️ Ruby/UnimplementedType

The Ruby SDK generator is not yet able to emit code for type {schema.type}; values will be passed through as-is and documented as Object for now

⚠️ Ruby/MultipleNamedModelsInIntersection

Multiple named models found in intersection, currently only 1 named model is supported: - {model_names.0} - {model_names.1}

⚠️ Ruby/DuplicateEnumName

Multiple enum members found with the same Ruby name "{name}", the duplicates have been renamed to avoid collisions

✍️ Ruby/UnnamedType

The Ruby SDK generator is not yet able to pick a meaningful name for this type, will use {generated_name} for now

✍️ Ruby/NameShadowedBuiltin

Renamed Ruby method from "{name}" to "{new_name}" to avoid shadowing a built-in method.

To provide a different name, use a merge transform.

✍️ Ruby/NameNotAllowed

Renamed illegal Ruby identifier from "{name}" to "{new_name}", because {reason}.

To provide a different name, use a merge transform.

Schema

❌ Schema/InconsistentEnumMembers

Enum members have different types.

Expected {expected_type} but found object. Ensure all enum values have the same type.

❌ Schema/RecursiveMustBeModel

Recursive schema ignored: {oas_path}

Add this schema to your Stainless config as a model to map it to a type. Otherwise, the type for this schema will be unknown.Based on where this schema is used, it can be added to #/resources/{recommended_resource_path.0}/subresources/{recommended_resource_path.1}.

❌ Schema/DirectlyReferencesSelf

Ignored schema which references itself.

This schema has recursive references to itself via its {combinator} key, so the following entries were ignored:

• {recursive_indices.0}
• {recursive_indices.1}

To resolve this issue, restructure this schema to avoid recursive self-references.

Self-referential schemas (schemas that reference themselves) have limited support. When encountered, only specific variants containing these self-references will be used, which may result in incomplete type definitions.

Example of a self-referential schema:

components:
  schemas:
    Node:
      oneOf:
        - type: string
        - $ref: '#/components/schemas/Node'

❌ Schema/ExternalReference

Schema $ref "{ref_name}" could not be resolved, is it an external reference? e.g. file or url

❌ Schema/TypeNotValid

Unsupported schema type {type}.

We support string, number, integer, boolean, array, object, and null types (case-sensitive).

You can use a transform to adjust the type used by Stainless, or change the type in your OpenAPI spec.

❌ Schema/CannotInferEnumMemberName

Unable to generate valid name for enum member {member_name} in {language}.

We were unable to create a valid name in {language} for {member_name}.

Use a Stainless transform to specify a different name appropriate for {language}, or change the name of this enum in your OpenAPI spec.

❌ Schema/PropertyNameCollision

{collisions.0} and {collisions.1} may render to the same name in some languages.

These properties have different names in your OpenAPI spec but may render to the same name in some languages.

Set explicit names using x-stainless-naming on the property schemas in your OpenAPI spec:

properties:
  {collisions.0}:
    x-stainless-naming:
      {language}:
        property_name: my_chosen_name

⚠️ Schema/EnumIsAmbiguous

Ignored enum because it only contained null.

Either add at least one non-null member, or use nullable: true or type: null instead of enum.

⚠️ Schema/ConstEnumHasMultipleMembers

Ignored x-stainless-const annotation.

This enum schema is marked as x-stainless-const: true, but has multiple members, so it will not be interpreted as const.

Remove all but one member, or remove x-stainless-const: true from the enum.

⚠️ Schema/TypeMissing

Could not infer a type for this schema.

Add an explicit type property to the schema.

⚠️ Schema/PatternNotValid

Ignored invalid pattern {pattern}, which may cause test failures.

Pattern is invalid, unsupported, or conflicts with this schema's minLength or maxLength.

Fix the regex pattern or use the autofix to remove it using the remove transform.

⚠️ Schema/EnumDescriptionNotValid

{reason}

⚠️ Schema/CannotInferName

Placeholder name generated for schema.

We were unable to infer a good name for this schema, so we gave it an arbitrary placeholder name.

To resolve this issue, do one of the following:

• Define a model
• Set a title property on the schema
• Extract the schema to #/components/schemas

For some schemas, the Stainless code generator cannot infer a name without additional information. This is usually because the schema is too complex or ambiguous.

For example, consider a schema that represents a string or an object:

oneOf:
  - type: string
  - type: object
    properties:
      id:
        type: string
      name:
        type: string

Some languages may need an explicit name for the object, but it's not clear what to call it.

⚠️ Schema/CannotInferUnionVariantName

Placeholder name generated for union variant.

We were unable to infer a good name for this union variant, so we gave it an arbitrary placeholder name.

To resolve this issue, do one of the following:

• Define a model
• Set a title property on the schema
• Extract the schema to #/components/schemas
• Provide a name by adding an x-stainless-variantName property to the schema containing the name you want to use

Or apply an auto-fix to extract it to #/components/schemas/{suggested_name}.

For some union variants, the Stainless code generator cannot infer a name without additional information. This is usually because the union is too complex or ambiguous.

For example, consider a union schema that represents one of:

• A string
• An array of string arrays or strings

oneOf:
  - type: string
  - type: array
    items:
      oneOf:
        - type: array
            items:
              type: string
        - type: string

Some languages may need an explicit name for the "array of string arrays or strings" variant, but it's not clear what to call it.

The auto-fix will add OpenAPI transformations to extract the inline schema to #/components/schemas and replace the original with a $ref.

⚠️ Schema/DeprecationMessageWithoutDeprecation

This schema has an x-stainless-deprecation-message, but it is not deprecated, so the message will have no effect.

Use the autofix to add deprecated: true, or remove x-stainless-deprecation-message.

⚠️ Schema/ConstAndEnumMismatch

This enum schema has both enum and const properties, but with different values, so {outcome}.

⚠️ Schema/DiscriminatedUnionVariantMissingProperty

Union variant doesn't define the property discriminator {property_name} which is required as the union schema defines discriminator.propertyName

✍️ Schema/ObjectHasNoProperties

Type information is missing for {oas_path}

This schema doesn't have properties or additionalProperties defined, so we're interpreting its type as unknown. For a better developer experience, we recommend you add type information to this schema.

If this schema has properties, add them as properties in your OpenAPI spec.

If this schema should be a map, add additionalProperties.

If this schema should be an empty object, add x-stainless-empty-object: true. (We don't consider a schema with type: object and no other information to be an empty object type.)

✍️ Schema/EnumHasOneMember

Confirm intentional use of enum with single member.

Typically, enums have more than a single member.

If this schema is an enum because it might have more members in the future, ignore this note.

If this enum will only ever have a single member, we recommend you define it as a const because some SDKs will set const properties as defaults for convenience.

If you want to change this to a const but you can't change your spec, add x-stainless-const: true to this schema to make Stainless treat this enum as a const.

✍️ Schema/DeprecatedWithoutMessage

Confirm schema is deprecated and add missing deprecation details if needed.

This schema has deprecated set to true, but there's no deprecation message associated with it.

If this schema isn't deprecated, remove deprecated: true.

If this schema is deprecated, add an x-stainless-deprecation-message property and set the value to a message that helps your users understand what to use instead of this schema. For example:

x-stainless-deprecation-message: 'Use /v2/some/method instead.'

✍️ Schema/StringFormatNotSupported

Confirm or change unsupported string format for {oas_path}

The format set for this string ({format}) is not supported by Stainless and was ignored.

If you have format set to {format} for documentation or other purposes, ignore this note.

Otherwise, use a format Stainless supports, or remove the format property.

Stainless supports the following string format values:

• binary
• byte
• date
• date-time
• time
• uri
• uuid

✍️ Schema/ArrayMissingItems

Array schema missing items definition.

This schema has type: array but no items property, so the element type is unknown.

Add an items definition to specify the array element type.

✍️ Schema/IsAmbiguous

Missing type for {oas_path}

This schema doesn't have a type, so we're interpreting it as unknown. This is usually an oversight; we recommend you add a type to this schema in your OpenAPI spec.

If this schema accepts any type, use the autofix or add x-stainless-any: true to suppress this note. If you have several schemas like this, use an update transform with matches_schema to update all of them without adding individual properties to each one.

✍️ Schema/EnumMemberTypeNotValid

Enum member has type "{member_type}" which is not a primitive type.

To fix, you may want to use a oneOf or anyOf instead of an enum definition.

✍️ Schema/EnumDuplicateMembers

Enum has duplicate members: {duplicates.0.value} and {duplicates.1.value}

Remove the duplicates with either a Stainless transform or a modification to your OpenAPI spec to clear this note.

✍️ Schema/MultipleEnumMemberTypes

Found enum members with different types ("{member_types.0}" and "{member_types.1}"). To fix, this should likely be an anyOf instead.

✍️ Schema/RequiredPropertyNotDefined

This schema marks {unknown_required_props.0} and {unknown_required_props.1} as required, but they aren't defined in properties, so they will be ignored.

Remove the properties from required or define them in properties.

Security

❌ Security/SchemeNotFound

Security scheme not found: {security_scheme_name}

Define this scheme in #/components/securitySchemes or remove it from your Stainless config.

❌ Security/InvalidSchemeRole

Invalid auth.role {invalid_role} for {security_scheme_name}.

Valid values: {valid_roles.0} or {valid_roles.1}.

⚠️ Security/DigestAuthNotSupported

Skipped digest authentication on unsupported targets.

The following SDK targets do not support digest authentication: {unsupported_targets.0} and {unsupported_targets.1}.

Contact support@stainless.com with your use case.

⚠️ Security/SchemeNotValid

Invalid security configuration was skipped: {security_scheme_name}

{reason}

You must have a client_settings.opts entry in your Stainless config for every security scheme in your OpenAPI spec. See our authentication configuration guide for details.

✍️ Security/MissingConfiguration

Authentication is not configured for your SDKs because there is no valid root-level security section in your Stainless config or OpenAPI spec. See our authentication guide for details.

Sql

⚠️ Sql/TooManyFunctionArgs

{name} could not be generated because it has {arg_count} > 100 args.

Streaming

❌ Streaming/UnsupportedParamsStructure

Streaming method uses a union type for request params which is not supported yet.

⚠️ Streaming/DuplicateFallthroughEvents

Ignored all kind: fallthrough events because multiple were declared.

on_event:
  {indices.0}: { kind: fallthrough, … }
  {indices.1}: { kind: fallthrough, … }

⚠️ Streaming/ConflictingEventTypeHandling

Ignored all handlers for event_type: {event_type} because multiple were declared.

The following handlers were declared for {event_type}:

• {handlers.0}
• {handlers.1}

✍️ Streaming/CannotInferParamsName

No model name, $ref or streaming.param_type_name defined - using default params type name

Terraform

❌ Terraform/ResourceCannotBeInferred

Issue with Terraform resource: {resource_name}

{detail}

❌ Terraform/ResourceHasAmbiguousProperties

Terraform resource has untyped properties: {resource_name}

Resources that contain untyped properties will result in raw JSON fields.

To resolve this issue, add type annotation to the following properties:

• {properties.0}
• {properties.1}

❌ Terraform/UnknownInUnion

Skipped union variant with undefined type.

Do one of the following to resolve this error:

• Use a Stainless transform to add type annotations for this variant or explicitly omit it with x-stainless-skip
• Add type annotations for this variant to your OpenAPI spec

❌ Terraform/UnsupportedAttributeRendering

Rendering {attribute_type} attributes as positional params in Go SDK requests is not yet supported and will be skipped.

⚠️ Terraform/UnsupportedRequest

({resource_name}) resource has an unsupported request type ({request_type}) in method {method.name}. Supported response types are: {supported_request_types.0}, {supported_request_types.1}.

⚠️ Terraform/UnsupportedResponse

({resource_name}) resource has an unsupported response type ({response_type}) in method {method.name}, and will be ignored. Supported response types are: {supported_response_types.0}, {supported_response_types.1}.

⚠️ Terraform/UnsupportedDeleteBehaviorUnspecified

({resource_name}) Could not find a delete operation. If the resource does not support deletion, provide a value for 'unsupported_delete_behavior'.

⚠️ Terraform/ResourceHasNamingCollision

({resource.name}) resource has a property with the name "{conflicting_name}" which conflicts with the name of the "{name}" {attribute_type} attribute. As an interim measure, To resolve, please {customer_action}.

⚠️ Terraform/DataSourceAttributeTypeMismatch

This resource has conflicting types between request and response for attribute {attribute_name}, so the request type will be used.

⚠️ Terraform/UnsupportedQueryType

({resource.name}) resource has a property "{attribute_name}" of type "{type}" which is currently unsupported in Terraform.

⚠️ Terraform/XStainlessAlwaysSendInvalid

The x-stainless-terraform-always-send extension is not permitted for property {attribute_name} and will be ignored.

This extension is only valid on computed and computed optional attributes with primitive types. The {attribute_name} property has type {type} and configurability {configurability}.

⚠️ Terraform/XStainlessConfigurabilityInvalid

The x-stainless-terraform-configurability value {configurability} is not allowed (possible values are: required, computed, optional, computed_optional).

⚠️ Terraform/XStainlessCollectionInvalid

The x-stainless-collection-type extension is not permitted for this property and will be ignored.

This extension is only permitted on properties with type array, but this property has type {schema.type}.

✍️ Terraform/PotentiallyConfusingPaginationAttribute

({resource.name}) resource has a property with the name "{attribute_name}" which could be a pagination attribute that should be abstracted away in Terraform.

Transform

❌ Transform/Failed

Stainless transform failed: {command}

Failed at step {step}:

{message}

See our transforms documentation for more details.

✍️ Transform/Useless

Transformation {command} had no effect on the OpenAPI schema and can safely be removed.

TypeScript

❌ TypeScript/NpmPackageNameNotValid

Invalid npm package name: {package_name}

{package_name} is not a valid npm package name, so we changed it to {fallback_package_name}.

We recommend you set an explicit npm package name in your Stainless config instead of relying on our fallback naming behavior.

⚠️ TypeScript/PublishingWithoutOIDC

Publishing security issue: trusted publishing with OIDC is not enabled.

You have publishing configured, but you haven't enabled trusted publishing with OIDC. We recommend you enable trusted publishing.

OIDC eliminates the security risks associated with long-lived write tokens, which can be compromised, accidentally exposed in logs, or require manual rotation.

With OIDC trusted publishing, each publish uses short-lived, cryptographically-signed tokens that are specific to your workflow and cannot be extracted or reused.

Unsupported

⚠️ Unsupported/WebSocketEventVariantIsNotAnObject

The event schema type ({schema.type}) is not object, this event variant will be skipped.

⚠️ Unsupported/WebSocketEventDiscriminatorValue

The event schema discriminator value ({value}) is not a string, no types will be generated for it.

⚠️ Unsupported/SkipAndOnly

Both skip and only are specified, but only skip will be respected.

Only one of skip and only can specified at once.

✍️ Unsupported/StubMethod

Stub methods are not currently supported for {language}

✍️ Unsupported/WebhookUnwrap

Webhook unwrap method tests are not currently supported for {language}

✍️ Unsupported/WebSocketMethod

WebSocket methods are not currently supported for {language}

WebSocket

❌ WebSocket/EventSchemaIsNotAUnion

Skipped generating WebSocket {from} event types.

The event schema must be a union type.

❌ WebSocket/EventSchemaIsNotADiscriminatedUnion

The event schema type ({schema.type}) is a union but it is not discriminated, no {from} event types will be generated.

You can mark a union schema as discriminated with the discriminator property:

oneOf:
  - $ref: '#/components/schemas/StartEvent'
  - $ref: '#/components/schemas/EndEvent'
discriminator:
  propertyName: 'type'

❌ WebSocket/MultipleMethodsOnResource

Multiple WebSocket methods on a single resource is not supported.

The following WebSocket methods are defined on the same resource:

• {method_names.0}
• {method_names.1}

⚠️ WebSocket/EventMissingDiscriminator

Skipped event with missing discriminator property {discriminator_property}.

Add the {discriminator_property} property to the event schema.

⚠️ WebSocket/EventDiscriminatorNotAnEnum

Skipped event because its discriminator type was not enum.

The discriminator property has type {schema.type}. Change it to an enum type.

⚠️ WebSocket/DependenciesRequiredButNoEndpoints

WebSocket dependencies are marked as required, but SDK has no WebSocket endpoints defined.

Either set settings.require_websocket_dependencies to false or add at least one WebSocket endpoint.

Webhook

❌ Webhook/OASWebhooksMissing

Skipped webhook_unwrap method because your OpenAPI spec does not have a webhooks section.

Add a top-level webhooks section to your OpenAPI spec or remove the webhook_unwrap method from your Stainless config.

❌ Webhook/OperationNotFound

Skipped webhook event type because {operation_name} is not in your OpenAPI spec's webhooks section.

Verify this operation name matches a key in your OpenAPI spec's top-level webhooks section or remove it from event_types in your Stainless config.

❌ Webhook/UnsupportedContentType

Skipped webhook event type because {operation_name} does not provide an application/json request body.

Stainless currently requires webhook operations to define an application/json request body schema. The configured webhook operation provides: {content_types.0}, {content_types.1}. Update the OpenAPI webhooks entry or remove it from event_types in your Stainless config.

Misc

💀 BootstrapCommandError

Bootstrap command failed after code generation: {command}

{command_output.contents}

This is likely an internal issue. Contact support@stainless.com if it persists.

💀 FormatterCommandError

Formatter command failed after code generation: {command}

{command_output.contents}

This is likely an internal issue. Contact support@stainless.com if it persists.

💀 FatalError

Generation failed due to an unexpected error.

"{error}"

If this issue persists, contact support@stainless.com.

💀 UserGeneratedFatalError

Build failed due to a configuration or spec error.

"{error}"

💀 OpenAPISpecFatalError

Unable to parse OpenAPI spec.

"{error}"

If this issue persists, contact support@stainless.com.

💀 MissingDependencySDK

The {dependent_language} SDK depends on the {missing_dependency} SDK

In order to build the {dependent_language} SDK, you must first set up and build the {missing_dependency} SDK. The {dependent_language} SDK uses the {missing_dependency} SDK as a dependency.

💀 NoHTTPMethodFound

Could not find a HTTP method. At least one endpoint must be defined to generate an SDK.

❌ InvalidInternalState

Internal error, please try again.

Something went wrong on our end, please try again.

If this issue persists, contact support@stainless.com and provide the following error message:

{error.message}

❌ BuildCommandError

Generation stopped because build command {command} failed.

{command_output.contents}

This is likely an internal issue. Contact support@stainless.com if it persists.

❌ LinterCommandError

A linter reported issues: {command}

❌ TestCommandError

A test command reported an error: {command}

❌ LinkCommandError

A link command reported an error: {command}

❌ UnlinkCommandError

A link command reported an error: {command}

⚠️ InvalidInternalStateWarning

Something unexpected happened during codegen. Our team has been notified. Your SDK was still generated correctly, and no action is needed on your end. If you need help please reach out to support@stainless.com.

{error.message}