Failure codes
Validator issues, gesso doctor diagnostics, and the coverage and strict gate verdicts carry a stable failure code. Text output shows it as [GSO212]; JSON output has code and docs_url fields. vendor/bin/gesso explain GSO212 prints the entry below in the terminal, and --format=json prints it for tools and agents.
Codes are a compatibility surface (versioning). A code keeps its meaning for the whole major line and is never reused; new codes may appear in minor releases. Ranges group the codes: GSO0xx general, GSO1xx request validation, GSO2xx response validation, GSO3xx doctor, GSO4xx coverage gates and merge, GSO5xx strict contract gates. GSO6xx-GSO9xx are reserved.
Usage errors (exit code 2) have no code: the message and the usage text say what to fix.
General (GSO0xx)
GSO001
Unclassified validation failure. The result was built by code that only passed error strings, so Gesso cannot say which validator produced it.
Validator issue category unknown.
Common causes:
- A custom integration calls
OpenApiValidationResult::failure()withoutissues:.
How to fix:
- Read the message for the actual problem.
- If you own the integration, pass
ValidationIssueobjects so the failure gets a specific code.
Do not match on the message text in CI; it is not a compatibility surface.
Request validation (GSO1xx)
GSO101
Request path is not in the spec. No path template in the spec matches the request path, so the request cannot be validated.
Validator issue category request.path_match.
Common causes:
- The endpoint is new and not documented yet.
- A base path or version prefix (
/api,/v1) is in the request but in neither the spec paths nor itsservers. - A trailing slash or a typo differs between the route and the spec.
How to fix:
- Spec wrong: add the path to
paths. - Prefix mismatch: declare the base path in the spec's
servers, or setspec.strip_prefixesingesso.php. - Test wrong: fix the URL the test calls. The failure lists the closest spec paths.
Do not skip the test with #[SkipOpenApi]; an undocumented endpoint is the drift contract testing exists to catch.
GSO102
Request method is not defined for the path. The path exists in the spec, but it declares no operation for this HTTP method.
Validator issue category request.method.
Common causes:
- The operation is missing from the spec.
- The test uses the wrong method (for example
PUTinstead ofPATCH).
How to fix:
- Spec wrong: add the operation under the path item.
- Test wrong: call the documented method.
Do not skip the test; an undocumented operation is real drift.
GSO103
Request side of the spec is malformed. A node the request validator needs (an operation, parameter, or request body) is not shaped as OpenAPI requires, so it cannot be enforced.
Validator issue category request.spec.
Common causes:
- A parameter is missing
nameorin, or has a non-object schema. - A
$refresolved to the wrong kind of object.
How to fix:
- Run
vendor/bin/gesso doctorfor the exact node and fix the spec.
Do not skip the test; a malformed spec node fails every request to this operation.
GSO104
Path parameter does not match its schema. A path parameter value does not satisfy the schema the spec declares for it.
Validator issue category request.parameter.path.
Common causes:
- The test passes a value of the wrong shape (a slug where the spec says integer).
- The spec schema is narrower than the application accepts.
How to fix:
- Test wrong: use a valid value.
- Spec wrong: widen the parameter schema.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO105
Query parameter is missing or does not match its schema. A required query parameter is absent, or a query value does not satisfy its schema. keyword is required when the parameter is missing.
Validator issue category request.parameter.query.
Common causes:
- The test omits a required parameter.
- A value has the wrong type or is outside an
enum. - The
style/explodeserialization differs from what the client sends.
How to fix:
- Test wrong: send the documented parameter.
- Spec wrong: fix
required, the schema, or the serialization fields.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO106
Header parameter is missing or does not match its schema. A required request header is absent, or its value does not satisfy its schema. keyword is required when the header is missing.
Validator issue category request.parameter.header.
Common causes:
- The test does not send the header.
- The value has the wrong format.
How to fix:
- Test wrong: send the header.
- Spec wrong: fix
requiredor the schema.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO107
Security requirement is not satisfied. No security requirement of the operation is satisfied. keyword is required when credentials are absent and format when they are present but unusable.
Validator issue category request.security.
Common causes:
- The test sends no credentials.
- The credential goes to a different header, query, or cookie than the scheme declares.
- The operation should be public but inherits root-level
security.
How to fix:
- Test wrong: send credentials (Laravel:
laravel.auto_inject_dummy_credentials). - Spec wrong: fix the scheme, or set
security: []on a public operation. - A scheme Gesso cannot check (for example
mutualTLS): list it invalidation.acknowledged_unvalidatable_schemes.
Do not remove security from the spec to make the test pass.
GSO110
Request body does not match its schema. The request body violates a schema keyword that has no more specific code. keyword names the failing keyword.
Validator issue category request.body.
Common causes:
- The test sends a body the spec does not allow.
- The spec schema is stricter than the application.
How to fix:
- Use
instance_pathandkeywordto find the field. - Test wrong: send a valid body.
- Spec wrong: fix the schema.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO111
Request body is missing a required property. An object in the request body lacks a property listed in required.
Validator issue category request.body with keyword required.
Common causes:
- The test omits a field.
- The spec marks a field required that the application treats as optional.
How to fix:
- Test wrong: send the field.
- Spec wrong: remove it from
required.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO112
Request body value has the wrong type. A request body value has a JSON type the schema does not allow.
Validator issue category request.body with keyword type.
Common causes:
- A number is sent as a string, or the reverse.
- A value is
nullbut the schema is not nullable.
How to fix:
- Test wrong: send the documented type.
- Spec wrong: widen
type(OpenAPI 3.0:nullable: true; 3.1+:type: [x, "null"]).
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO113
Request body has an undeclared property. The request body has a property the schema forbids through additionalProperties: false or unevaluatedProperties: false.
Validator issue category request.body with keyword additionalProperties or request.body with keyword unevaluatedProperties.
Common causes:
- The client sends a field the spec does not document.
- A typo in a property name.
How to fix:
- Spec wrong: document the property.
- Test wrong: stop sending it.
Do not set additionalProperties: true only to silence this.
GSO114
Request body value is not an allowed value. A request body value is not in the schema's enum, or differs from its const.
Validator issue category request.body with keyword enum or request.body with keyword const.
Common causes:
- A new enum value was added in code but not in the spec.
- Case or spelling differs.
How to fix:
- Spec wrong: add the value to
enum. - Test wrong: send an allowed value.
Do not drop the enum from the spec only to silence this.
GSO115
Request body value does not match its format. A request body string does not satisfy the schema format (date-time, uuid, email, ...).
Validator issue category request.body with keyword format.
Common causes:
- A date is sent without a time zone or in another layout.
- The spec declares a stricter format than the application uses.
How to fix:
- Test wrong: send a value in the documented format.
- Spec wrong: change or remove
format.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO116
Request body cannot be decoded. The request body could not be read or parsed for its content type (for example invalid JSON), so its schema could not be checked.
Validator issue category request.body with keyword parse.
Common causes:
- The test sends malformed JSON.
- The
Content-Typeheader does not match the body.
How to fix:
- Send a body that parses as its declared content type.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
Response validation (GSO2xx)
GSO201
Response request context is not in the spec. The path or method of the request that produced this response is not in the spec, so the response has no operation to check against.
Validator issue category response.request_context.
Common causes:
- The endpoint is undocumented.
- A path prefix is not stripped (
spec.strip_prefixes).
How to fix:
- Spec wrong: add the path or operation.
- Prefix mismatch: declare the base path in
servers, or setspec.strip_prefixes. - Test wrong: call the documented path.
Do not skip the test with #[SkipOpenApi]; an undocumented endpoint is real drift.
GSO202
Response side of the spec is malformed. A node the response validator needs (responses, a response object, or its content) is not shaped as OpenAPI requires.
Validator issue category response.spec.
Common causes:
responsesis not an object.- A
$refresolved to the wrong kind of object.
How to fix:
- Run
vendor/bin/gesso doctorfor the exact node and fix the spec.
Do not skip the test; a malformed spec node fails every response of this operation.
GSO203
Response status is not documented. The operation declares no response for this status code, no matching range (4XX), and no default.
Validator issue category response.status.
Common causes:
- An error path returns a status the spec does not list (often 401, 403, 404, 422).
- The application returns the wrong status.
How to fix:
- Spec wrong: document the response.
- Implementation wrong: return the documented status.
Do not list the status in validation.skip_response_codes to hide an undocumented response.
GSO204
Response header is missing or does not match its schema. A required response header is absent, or its value does not satisfy its schema. keyword is required when the header is missing.
Validator issue category response.header.
Common causes:
- The application does not set the header on this path.
- The value has the wrong format.
How to fix:
- Implementation wrong: set the header.
- Spec wrong: fix
requiredor the schema.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO205
Response media type is not declared. The response arrived as a JSON media type the spec does not declare for this status, so the body was checked against another JSON entry. Read it together with the body failure next to it.
Validator issue category response.content_type.
Common causes:
- The application returns
application/problem+jsonbut the spec only declaresapplication/json, or the reverse.
How to fix:
- Spec wrong: declare the media type.
- Implementation wrong: send the documented
Content-Type.
Do not delete the content entry to make the body check go away.
GSO210
Response body does not match its schema. The response body violates a schema keyword that has no more specific code. keyword names the failing keyword.
Validator issue category response.body.
Common causes:
- The application returns a body the spec does not allow.
- The spec is out of date.
How to fix:
- Use
instance_pathandkeywordto find the field. - Decide which side is wrong, then fix the implementation or the schema.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO211
Response body is missing a required property. An object in the response body lacks a property listed in required.
Validator issue category response.body with keyword required.
Common causes:
- The serializer omits a field when it is null or empty.
- The spec marks a field required that is optional in practice.
How to fix:
- Implementation wrong: always serialize the field (as
nullif the schema allows it). - Spec wrong: remove it from
required.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO212
Response body value has the wrong type. A response body value has a JSON type the schema does not allow.
Validator issue category response.body with keyword type.
Common causes:
- A value is
nullbut the schema is not nullable. - A numeric string is returned where the spec says number, or the reverse.
- An empty PHP array serializes as
[]where the schema expects an object.
How to fix:
- Implementation wrong: cast the value.
- Spec wrong: widen
type(OpenAPI 3.0:nullable: true; 3.1+:type: [x, "null"]).
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO213
Response body has an undeclared property. The response body has a property the schema forbids through additionalProperties: false or unevaluatedProperties: false.
Validator issue category response.body with keyword additionalProperties or response.body with keyword unevaluatedProperties.
Common causes:
- The application returns a field the spec does not document yet.
- A resource leaks an internal field.
How to fix:
- Spec wrong: document the property.
- Implementation wrong: stop returning it.
Do not set additionalProperties: true only to silence this.
GSO214
Response body value is not an allowed value. A response body value is not in the schema's enum, or differs from its const.
Validator issue category response.body with keyword enum or response.body with keyword const.
Common causes:
- A PHP enum gained a case the spec does not list (see enum drift).
How to fix:
- Spec wrong: add the value to
enum. - Implementation wrong: return an allowed value.
Do not drop the enum from the spec only to silence this.
GSO215
Response body value does not match its format. A response body string does not satisfy the schema format (date-time, uuid, email, ...).
Validator issue category response.body with keyword format.
Common causes:
- A date is serialized without a time zone or in another layout.
How to fix:
- Implementation wrong: serialize in the documented format.
- Spec wrong: change or remove
format.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
GSO216
Response body cannot be decoded. The response body could not be read or parsed for its content type (for example invalid JSON), so its schema could not be checked.
Validator issue category response.body with keyword parse.
Common causes:
- The application emits debug output or a PHP warning before the JSON.
- The
Content-Typeheader does not match the body.
How to fix:
- Implementation wrong: return a body that parses as its declared content type.
Do not add #[SkipOpenApi], list the status in validation.skip_response_codes, or regenerate the violation baseline to make this pass.
Doctor diagnostics (GSO3xx)
GSO301
Spec file cannot be read. The spec path does not name a readable file.
gesso doctor issue category io.
Common causes:
- A wrong path or
spec.base_path. - File permissions.
How to fix:
- Check the path and the permissions.
Do not remove the spec from spec.names to make doctor pass.
GSO302
Spec cannot be parsed. The spec is not valid JSON or YAML, has an unsupported extension, or its root is not a mapping.
gesso doctor issue category parser.
Common causes:
- A syntax error.
- A YAML spec without
symfony/yamlinstalled.
How to fix:
- Fix the syntax.
- For YAML:
composer require --dev symfony/yaml.
Do not convert the spec by hand to dodge the parser; fix the source.
GSO303
OpenAPI version is missing or unsupported. The openapi field is missing, or names a version Gesso does not support (3.0, 3.1, and 3.2 are supported).
gesso doctor issue category version.
Common causes:
- A Swagger 2.0 document.
- A typo in the
openapifield.
How to fix:
- Convert Swagger 2.0 to OpenAPI 3.x.
- Set
openapito the version the document follows.
Do not change the version number without converting the document.
GSO304
JSON Schema dialect is unsupported. jsonSchemaDialect or a schema $schema names a dialect Gesso cannot enforce.
gesso doctor issue category dialect.
Common causes:
- A custom or draft dialect URI.
How to fix:
- Use the OpenAPI default dialect for the document version.
Do not remove the dialect declaration if the schemas really depend on it.
GSO305
Reference cannot be resolved. A $ref points to a missing target, a file outside the allowed root, a remote document that is not allowed, or forms a cycle Gesso cannot follow.
gesso doctor issue category references.
Common causes:
- A typo in the pointer.
- A remote
$refwithout--allow-remote-refs. - A local file outside
--local-ref-root.
How to fix:
- Fix the pointer.
- Bundle the spec, or allow the exact remote host or local root.
Do not widen the allowed reference root beyond the directory you trust.
GSO306
Spec structure is invalid. A node has the wrong shape for OpenAPI (for example paths is not an object, or a discriminator is inconsistent). Runtime validation fails on the same node.
gesso doctor issue category structure.
Common causes:
- A hand edit broke a node.
- A generator emitted an invalid node.
How to fix:
- Fix the node the message names.
Do not disable discriminator enforcement only to make doctor pass.
GSO307
Schema keyword or format is not enforced. The spec uses a keyword or format Gesso does not enforce, so values that violate it pass.
gesso doctor issue category keyword.
Common causes:
- A vendor format, or a keyword outside the selected dialect.
How to fix:
- Accept the gap knowingly, or express the rule with a keyword Gesso enforces (
pattern,enum, ...).
Do not assume the constraint is tested.
GSO308
Spec feature is not validated. Doctor reports a feature Gesso skips (for example webhooks or an unvalidatable security scheme). This is reported as skipped, not as an error.
gesso doctor issue category feature.
Common causes:
- The spec uses a feature outside what runtime validation checks.
How to fix:
- See the supported-features page. For security schemes, acknowledge them in
validation.acknowledged_unvalidatable_schemes.
Do not read a clean doctor run as proof that skipped features are tested.
GSO309
Optional dependency is missing. An option needs a package that is not installed.
gesso doctor issue category dependency.
Common causes:
--allow-remote-refswithout a PSR-18 HTTP client.
How to fix:
- Install the package the message names.
Do not drop the option if the spec needs it; bundle the spec instead.
GSO310
Configuration is inconsistent with the spec. gesso.php or the doctor options name a spec, prefix, or setting the runtime would reject or never use.
gesso doctor issue category configuration.
Common causes:
- A
spec.namesentry that leavesspec.base_path. - A stale
spec.strip_prefixesorspec.default.
How to fix:
- Fix the configuration key the message names.
Do not delete the key without checking what it was for.
GSO311
Spec is invalid. The loader rejected the spec for a reason that has no more specific code.
gesso doctor issue category spec.
Common causes:
- See the message.
How to fix:
- Fix the spec as the message describes.
Do not skip the spec; runtime validation rejects it the same way.
GSO312
Spec uses a construct with limited support. The spec loads, but uses a construct Gesso handles with a documented limitation.
gesso doctor issue category compatibility.
Common causes:
- A construct listed under known limitations.
How to fix:
- Read the warning and the supported-features page.
Do not ignore the warning without reading the limitation.
GSO313
Doctor failed internally. Doctor hit an unexpected error while analysing the spec.
gesso doctor issue category internal.
Common causes:
- A bug in Gesso.
How to fix:
- Report it with the spec and the stack trace at https://github.com/studio-design/gesso/issues.
Do not assume the spec is fine; the check did not complete.
GSO314
Example does not match its schema. An example or examples value fails validation against the schema it illustrates. This is reported as a warning: the spec is enforceable, but the example drifted from it.
gesso doctor issue category example.
Common causes:
- The schema changed and the example was not updated.
- The example was written by hand and has a typo or a wrong type.
- A YAML spec writes a date-time unquoted in a spelling that is not kept (
2024-01-01 12:00:00is read as2024-01-01T12:00:00), so quote it.
How to fix:
- Example wrong: update it to a value the schema accepts.
- Schema wrong: fix the schema, then re-run your tests.
Do not delete the example only to silence doctor; generated docs, mocks, and SDKs read it.
Coverage gates and merge (GSO4xx)
GSO401
Changed operation is not covered. coverage:gate found a response whose operation changed against the base spec, and no test validated it in this run.
Emitted by gesso coverage:gate.
Common causes:
- The pull request changed an operation and added no test for it.
- The coverage document is from another run or another spec (
--spec-name).
How to fix:
- Add a test that validates the listed response.
- Check that
--coveragecomes from this run.
Do not exclude the operation or point --base-spec at the changed spec to pass the gate.
GSO402
Coverage is below the threshold. Endpoint, response, or SDK exercise coverage is below the configured coverage.min_coverage threshold.
Emitted by the coverage threshold gate (PHPUnit extension and gesso coverage:merge).
Common causes:
- New operations without tests.
- A partial test run.
How to fix:
- Add tests for the uncovered responses the report lists.
- Run the full suite before gating.
Do not lower the threshold to the current number; consider a coverage baseline, which fails on new gaps by name.
GSO403
Response is uncovered and not in the coverage baseline. A declared response was not validated in this run and is not listed in the coverage baseline file.
Emitted by the coverage baseline (PHPUnit extension and gesso coverage:merge).
Common causes:
- A new response in the spec without a test.
- A test that used to cover it was removed or skipped.
How to fix:
- Add a test that validates the response.
Do not regenerate the coverage baseline (GESSO_BASELINE_GENERATE=1) only to accept the gap.
GSO404
Coverage baseline entry is covered now. A response listed in the coverage baseline was validated in this run, so the entry is stale.
Emitted by the coverage baseline (PHPUnit extension and gesso coverage:merge).
Common causes:
- A test now covers the response.
How to fix:
- Remove the entry, or regenerate the baseline with
GESSO_BASELINE_GENERATE=1.
Do not set baseline_stale.coverage to off to hide stale entries.
GSO405
Parallel run is incomplete. A worker failed to write its coverage sidecar, or the number of sidecars differs from --expect-sidecars, so the merged report would be wrong.
Emitted by gesso coverage:merge.
Common causes:
- A worker crashed or was cancelled.
- Sidecars from another run are in the directory.
- A wrong
--expect-sidecarscount.
How to fix:
- Re-run the failed shard.
- Use
GESSO_RUN_IDto keep runs apart. - Correct
--expect-sidecars.
Do not delete the failure markers or drop --expect-sidecars to make the merge pass.
GSO406
No coverage was recorded. The run validated no response, so no coverage gate can be evaluated. It fails the run when a strict coverage threshold or the coverage baseline is configured, and is a warning otherwise.
Emitted by the coverage threshold gate and the coverage baseline (PHPUnit extension and gesso coverage:merge).
Common causes:
- The PHPUnit extension is not registered.
- The workers wrote no sidecars, or the merge reads the wrong directory.
- No test calls an assertion.
How to fix:
- Register the extension and check
coverage.sidecar_dir.
Do not turn off coverage.min_coverage.strict to make this pass.
Strict contract gates (GSO5xx)
GSO501
Always-present response field is not required. Strict-required detection saw a field in every observed response, but the schema does not list it in required.
Emitted by the strict-required gate (PHPUnit extension and gesso coverage:merge).
Common causes:
- The spec under-declares
required.
How to fix:
- Spec wrong: add the field to
required. - If the field is really optional, add a test whose response omits it.
Do not switch strict.required.run to off to silence the report.
GSO502
Undocumented response property was observed. Strict additional-properties detection saw a response property the schema does not declare.
Emitted by the strict additional-properties gate (PHPUnit extension and gesso coverage:merge).
Common causes:
- The application returns fields the spec does not document.
How to fix:
- Spec wrong: document the property.
- Implementation wrong: stop returning it.
Do not switch strict.additional_properties.run to off to silence the report.