Skip to main content

Generator diagnostics and errors

  • 💀 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.

ClientOpt​

⚠️ ClientOpt/UnnecessarilyRequired

client_settings.opts.{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 .

Endpoint​

❌ 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/NotFound

{endpoint} was not found in the OpenAPI spec, so code will not be generated for it.

❌ Endpoint/NotHttp

{endpoint} is not an HTTP endpoint, but only HTTP endpoints are supported, so code will not be generated for it.

An HTTP endpoint must contain:

  1. get, post, put, patch or delete
  2. Then a space
  3. Then a path that begins with a /

⚠️ Endpoint/NotConfigured

{endpoint} exists in the OpenAPI spec, but isn't specified in the Stainless config, so code will not be generated for it.

Did you mean {closest_endpoint}?

✍️ 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.

Go​

❌ Go/DuplicateVariantNameForUnion

Variant names for union {type_name} at {oas_path} overlap, as we could not infer good unique names for the variants.

These are the overlapping schemas:

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

You can assign better names to these schemas by assigning a title or making the variant a model.

❌ Go/SnippetNotValid

Go example snippet did not format correctly

⚠️ Go/NameNotAllowed

{reason}

⚠️ Go/SchemaVariantRequiresDiscriminator

Variant for union requires a property for discriminator {discriminator_property_name}

⚠️ Go/SchemaVariantTypeNotSupported

Variant type '{variant_type}' is not currently supported

✍️ Go/DuplicateVariantDeserializationConditions

The same deserialization condition deserializes to separate types:

{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}

✍️ Go/MultipleFormatsInUnion

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

✍️ Go/SchemaUnionRequiresDiscriminator

A discriminator field should be present on this union for Go, which helps deserialization.

Java​

❌ Java/UnsupportedAliasModel

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

✍️ 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 annotate either the union or the enum variant as a model.

✍️ Java/NameNotAllowed

{reason}

✍️ Java/SchemaUnionRequiresDiscriminator

A discriminator field should be present on this union for Java, which helps deserialization.

Java unions with more than one object variant, but no discriminator field, can be inefficient to deserialize at best and ambiguous to deserialize at worst.

Method​

❌ Method/NameNotValid

Method name invalid, please rename it: {reason}

⚠️ Method/ExpectedMatchPaginationScheme

Expected method to have matched pagination scheme {pagination_scheme} because it was explicitly configured in the method config.

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

Expected method to have not matched a pagination scheme because {reason}.

There were matches of these pagination styles:

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/MatchedMultiplePages

Found multiple matching pagination schemes, {pages.0} and {pages.1}. Add an explicit pagination: {page_name} to the method definition to disambiguate.

⚠️ Method/PaginatedWithoutMatchingScheme

{path} is paginated, but does not match any pagination scheme, so it will not be interpreted as paginated.

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/PathComponentMissingParameter

This endpoint is missing a parameter for path component {component}.

⚠️ Method/RequestBodyNotSupported

The endpoint is a GET method but has a request body. This is not recommended and will crash for JS fetch users.

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/BodyRootParamNeedsName

Encountered method with a non-object request body, defaulting to the name {fallback_name} for the generated method argument.

To change this, set body_param_name in the method config, e.g.

methods:
  my_method:
    type: http
    endpoint: post /examples
    body_param_name: 'items'

✍️ Method/PathHasRepeatedComponent

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

✍️ Method/RequestBodyHasAdditionalProperties

Request params schema defines additionalProperties but it will be ignored

Model​

❌ Model/DuplicateName

Another model with name {existing_model_name} already exists. Models should always have a unique name, or a unique namespaced name under a resource declared as a standalone_api.

❌ Model/NotFound

{path} was not found in the Stainless config, so it will be ignored.

⚠️ Model/DuplicateDefinition

Schema {ref_name} is already declared as a model at {existing_model_name}; One of the model definitions should be removed.

⚠️ Model/ParamsSuffixNameClash

Model config no_params_suffix is set to true but the schema is used in a response so removing the suffix would cause a name clash.

✍️ 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.

✍️ Model/NeedsRename

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

✍️ Model/Recommended

{oas_path} could potentially be defined as a model within {recommended_resource}.

The duplicated schema definition is not defined as a model so it will be duplicated in the generated code, even if the schema definition is shared using a $ref.

If this is intentional, then ignore this note. Otherwise, consider defining the schema as a model so that it's defined once in the generated code, and then referenced multiple times.

# In {recommended_resource}
models:
  {recommended_model}: "{oas_path}"

OAS​

❌ OAS/ReferenceNotFound

Reference pointed to by {ref_location} is missing from spec: {missing_pointer}

✍️ OAS/InvalidExample

Example is not valid for schema

Example: "{value}"

{reason}

✍️ OAS/InvalidUnionExample

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

Pagination​

❌ Pagination/DuplicatePurpose

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

❌ Pagination/ExpectedItemsToBeObject

Expected paginated items schema to be an 'object' type.

❌ Pagination/MissingProperty

Could not infer a response property with a '{purpose}' purpose as there were 16 applicable properties {inferred_schemas.0.schema.property_info.key} and {inferred_schemas.1.schema.property_info.key}.

You need to explicitly declare which response property should be used {used_for}. For example:

{in}:
  {example}

❌ Pagination/UnsupportedItemsSchemaType

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

❌ 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/UnusedPurposeConfig

Explicit pagination purpose config is defined but it was not used. Is '{schema.raw_schema.x_stainless_pagination_property.purpose}' a supported purpose for the '{page.type}' pagination type?

⚠️ Pagination/DuplicateName

A pagination config with the name {name} was declared multiple times.

These pagination configs conflict with each other:

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

ParamModel​

❌ ParamModel/ResponseAndParamSchemasMismatch

Cannot generate {cannot_generate_name} for {response_model.stainless_path}.

{response_model.raw_name}'s schema is incompatible with {param_model.stainless_path}'s schema.

❌ ParamModel/ResponseSchemaMissingRequiredParamSchemaProperty

Missing matching required property {missing_property_name} present on {param_schema.stainless_path}.

These properties must match to generate {cannot_generate_name} for {response_model.stainless_path}.

✍️ ParamModel/ResponseAndParamPropertySchemasMismatch

Property {mismatched_property_name}'s schema mismatches the same property on {param_schema.stainless_path}.

The property will be ignored when generating {cannot_generate_name} for {response_model.stainless_path}.

Parameter​

❌ Parameter/SchemaTypeNotValid

Schema type {type} is not a valid path param type; Expected one of {supported_types.0} or {supported_types.1}

⚠️ Parameter/DuplicateName

Found parameter with duplicate parameter name {param.name} in {param.location}.

This should be explicitly renamed using x-stainless-param:

- command: mergeObject
  reason: ...
  args:
    target: '{param.method.json_path}.parameters[?(@.name == "{param.key}" && @.in == "{param.location}")].schema'
    object:
      x-stainless-param: other_{param.name}

⚠️ Parameter/MissingName

The parameter name is missing or empty. It should be given a name.

⚠️ Parameter/MissingSchema

No schema for parameter is defined, assuming it's a schema of type: string

⚠️ Parameter/NotFound

Got an unknown param in positional_params: {path}

⚠️ Parameter/NotValid

{reason}

✍️ Parameter/HeaderIsNullable

A header parameter of type: null or with nullable: true is not supported and will be ignored

✍️ Parameter/NameHasBrackets

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

✍️ Parameter/PathIsNullable

A path parameter of type: null or with nullable: true is not supported and will be ignored

Python​

❌ Python/PackageNameNotAllowed

Package name {package_name} is not allowed.

❌ Python/RequestParamShadowsDefault

Request param '{name}' would shadow a request option with the same name

⚠️ Python/DuplicateDeclaration

We generated two separated types under the same name: {typename}. If they are the referring to the same type, they should be extracted to the same ref and be declared as a model. Otherwise, they should be renamed with x-stainless-naming

⚠️ Python/NameNotAllowed

{reason}

⚠️ Python/PyPiPackageNameDeprecated

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

QuerySettings​

⚠️ QuerySettings/BracketsFormatMustBeSet

The spec names array query params with brackets (e.g my_param[]). To support this, configure query_settings.array_format: brackets in the Stainless config.

Readme​

⚠️ Readme/MissingPaginationSnippet

Pagination has been configured but there is no readme.example_requests.pagination snippet defined

⚠️ Readme/MissingStreamingSnippet

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

ReadmeExample​

❌ ReadmeExample/CustomConfigNotValid

{reason}

⚠️ 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; The '{suggestion.method.endpoint}' endpoint has a nested parameter, '{suggestion.param.key}'.

✍️ ReadmeExample/MissingParam

{reason}

✍️ ReadmeExample/UnknownProperty

{reason}

Reference​

❌ Reference/NotASchema

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

❌ Reference/NotFound

{ref} was not found in the OpenAPI spec, so it will be ignored.

Did you mean {closest_ref}?

Resource​

❌ Resource/HasConflict

p has a name that conflicts with one or more resources, which may cause errors in the generated code.

Merge these resources into one to resolve the error:

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

❌ Resource/NotFound

{path} was not found in the Stainless config, so it will be ignored.

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/SchemaTypeNotValidForText

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

✍️ Response/UnsupportedContentType

Did not find a supported operation response content type; Received {content_types.0} and {content_types.1}

Ruby​

❌ Ruby/PaginationTypeUnsupported

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

❌ Ruby/UnexpectedParams

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

⚠️ Ruby/MultipleNamedModelsInIntersection

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

⚠️ Ruby/NameNotAllowed

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

Please rename it using the 'renameValue' transform.

⚠️ Ruby/NameShadowedBuiltin

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

Please rename it using the 'renameValue' transform.

⚠️ Ruby/SnippetNotFormatted

Ruby snippet did not format correctly and may have a syntax error.

⚠️ Ruby/UnimplementedType

The beta 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/UnnamedType

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

Schema​

❌ Schema/CannotInferEnumMemberName

Could not generate name for enum member {member_name} in language {language}

❌ Schema/CannotInferName

Sorry, the {language} codegen currently doesn't support inferring the name for this specific schema.

To explicitly set a schema name, either

  • set a title property on the schema
  • set a x-stainless-name OpenAPI extension on the schema
  • or extract that part of the OpenAPI spec to its own named schema component

For some languages and schemas, Stainless isn't able to infer a name. This is usually because the schema is too complex or ambiguous for a valid name to be generated. E.g. {oneOf: [{type: 'array', items: {oneOf: [...]}}]}.

To fix this, you can set a name explicitly in the schema via the title property, the x-stainless-name OpenAPI extension, or by extracting the problematic schema to its own named component.

❌ Schema/ExternalReference

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

❌ Schema/InconsistentEnumMembers

Inconsistent enum member type encountered, expected {expected_type} but received object

❌ Schema/RecursiveMustBeModel

Schema $ref: '{recursive_ref_name}' is recursively referenced and should be added as a model to the Stainless config.

❌ Schema/TypeNotValid

Schema type {type} is not a part of the JSON Schema specification and not supported by Stainless.

⚠️ Schema/CannotInferUnionVariantName

Could not infer a name for the union variant.

The name for a union variant is inferred from

  • a model definition
  • a title property on a schema
  • or a x-stainless-variantName OpenAPI extension on the schema

⚠️ Schema/DiscriminatedUnionVariantMissingProperty

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

⚠️ Schema/EnumDescriptionNotValid

{reason}

⚠️ Schema/EnumIsAmbiguous

Schema defines an enum property that only includes null.

Either at least one member should be added, or use nullable: true or type: null instead of enum.

⚠️ Schema/TypeMissing

Schema is missing a type property, and it was not automatically inferred.

✍️ Schema/ArrayMissingItems

{reason}

✍️ Schema/EnumDuplicateMembers

Enum has duplicate members: {duplicates.0} or {duplicates.1}

✍️ 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/IsAmbiguous

{oas_path} does not have at least one of type, oneOf, anyOf, or allOf, so its type has been interpreted as unknown.

If the schema should have a specific type, then add type to it.

If the schema should accept anything, then add x-stainless-any: true to suppress this note. If there are many such schemas, then use the replaceMatchingSchemas transform to update them all.

✍️ 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/ObjectHasNoProperties

{oas_path} has neither properties nor additionalProperties so its type has been interpreted as unknown.

If the schema should be a map, then add additionalProperties to it.

If the schema should be an empty object type, then add x-stainless-empty-object: true to it. A schema with just type: object and no other information is not interpreted as an empty object type.

✍️ Schema/RequiredPropertyNotDefined

Found properties in required that aren't defined as properties ("{unknown_required_props.0}" and "{unknown_required_props.1}").

To fix, either those entries should be removed from required or added to properties.

✍️ Schema/StringFormatNotSupported

{oas_path} specifies format: {format}, which is unsupported, so the format property will be ignored.

A string schema's format property can be set to binary, byte, date, date-time, time, uri or uuid.

If this is for documentation or other purposes, then ignore this note. Otherwise, remove the property or specify a supported format.

Security​

❌ Security/InvalidSchemeRole

{invalid_role} is not a valid auth.role for security_scheme {security_scheme_name}.

{security_scheme_name}'s auth.role can be set to {valid_roles.0} or {valid_roles.1}.

❌ Security/SchemeNotFound

Could not find security scheme: {security_scheme_name}

❌ Security/SchemeNotSupported

Security scheme not yet supported: {security_scheme_name}. Please contact support@stainlessapi.com with your use-case, and we can likely add this.

⚠️ Security/SchemeNotValid

Invalid security scheme '{security_scheme_name}': {reason}

✍️ Security/MissingConfiguration

No valid root-level 'security' section in your Stainless config or OpenAPI specification files, so authentication is not configured for your SDKs. See https://app.stainlessapi.com/docs/guides/configure#authentication for details.

Streaming​

❌ Streaming/UnsupportedParamsStructure

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

✍️ Streaming/CannotInferParamsName

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

Terraform​

❌ Terraform/ResourceCannotBeInferred

({resource_name}) {detail}

❌ Terraform/ResourceHasAmbiguousProperties

({resource_name}) resource has some properties with an undefined type, which results in a raw JSON field. To resolve, add type annotations to the following properties:

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

❌ Terraform/UnknownInUnion

One of the variants in a union has an undefined type, so it was omitted. Add type annotations to the variant have it included, or use x-stainless-skip to omit the variant explicitly.

⚠️ Terraform/DataSourceAttributeTypeMismatch

({resource.name}) resource has multiple methods with conflicting types for attribute "{attribute_name}", which is omitted as a data source parameter.

⚠️ 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/UnsupportedDeleteBehaviorUnspecified

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

⚠️ Terraform/UnsupportedQueryType

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

⚠️ 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/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

Transformation {command} at step {step} exited with a failure

{message}

Unsupported​

❌ Unsupported/MixOfArrayQueryParamFormat

The OpenAPI spec has a mixture of bracket and non-bracket query params, which is not supported by Stainless.

✍️ Unsupported/WebhookUnwrap

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

Misc​

💀 FatalError

Fatal error while generating code

💀 FormatterCommandError

A formatter reported an error: {command}

❌ BootstrapCommandError

A bootstrap command reported an error: {command}

❌ InvalidInternalState

{message}

❌ LinterCommandError

A linter reported issues: {command}

❌ TestCommandError

A test command reported an error: {command}