Troubleshooting & FAQ
Common issues
Section titled âCommon issuesââCannot listen on :8080â
Section titled ââCannot listen on :8080ââThe port is already in use. Either stop the other process or use a different port:
mimikos start --port 3000 petstore.yamlResponses contain null for nested objects
Section titled âResponses contain null for nested objectsâYour spec likely has deeply nested or circular schemas. Increase the max depth:
mimikos start --max-depth 15 petstore.yamlThe default is 10. Circular schemas terminate at the depth limit with null for objects and [] for arrays.
âEndpoint will return an errorâ warning at startup
Section titled ââEndpoint will return an errorâ warning at startupâThe response schema for that endpoint failed to compile. The startup banner shows which endpoints are affected. Check the warning log for the specific compilation error â it usually points to an invalid $ref or unsupported schema construct.
If the spec defines a media-type example for that endpoint, the example will still be served despite the degraded schema.
POST returns generated data, not my request body
Section titled âPOST returns generated data, not my request bodyâIn deterministic mode (the default), POST returns a generated response based on the spec schema. Your request body is validated but not echoed back.
Switch to stateful mode to get CRUD behavior where POST stores your data:
mimikos start --mode stateful petstore.yamlGET returns data before any POST (stateful mode)
Section titled âGET returns data before any POST (stateful mode)âIn stateful mode, GET on a collection returns an empty array until you POST something. GET on an item returns 404 until that specific resource exists.
If youâre seeing generated data on GET, youâre in deterministic mode (the default).
Response doesnât match my spec
Section titled âResponse doesnât match my specâEnable strict mode to surface validation failures:
mimikos start --strict petstore.yamlIn strict mode, any generated response that fails schema validation returns a 500 error with details about what went wrong. In default mode, validation failures are logged as warnings but the response is still sent.
macOS: âmimikos cannot be opened because it is from an unidentified developerâ
Section titled âmacOS: âmimikos cannot be opened because it is from an unidentified developerââThe pre-built binary may be blocked by macOS on first run. Remove the quarantine flag:
xattr -d com.apple.quarantine mimikosOr install via go install to build from source:
go install github.com/mimikos-io/mimikos/cmd/mimikos@latestWhat OpenAPI versions are supported?
Section titled âWhat OpenAPI versions are supported?âOpenAPI 3.0 and 3.1. Both YAML and JSON spec formats. OpenAPI 2.0 (Swagger) is not supported.
Is the output stable across versions?
Section titled âIs the output stable across versions?âDuring 0.x.y development, response output may change between releases. Pin a version that works for your tests. Starting from 1.0.0, output stability will be a versioning guarantee.
Can I use Mimikos in CI?
Section titled âCan I use Mimikos in CI?âYes. Deterministic mode is designed for CI â same request always returns the same response, no state to set up or tear down. Download a pre-built binary in your CI pipeline:
curl -L https://github.com/mimikos-io/mimikos/releases/latest/download/mimikos_linux_amd64.tar.gz | tar xz./mimikos start petstore.yaml &# Run your testsDoes Mimikos support multiple specs?
Section titled âDoes Mimikos support multiple specs?âOne instance serves one spec. Run multiple instances on different ports for multiple specs:
mimikos start --port 8080 users-api.yaml &mimikos start --port 8081 orders-api.yaml &What happens when a schema fails to compile?
Section titled âWhat happens when a schema fails to compile?âMimikos reports degraded schemas in the startup banner so you know which endpoints are affected. The behavior depends on whether strict mode is enabled:
| Situation | Default mode | Strict mode |
|---|---|---|
| Response schema degraded | Endpoint returns an error response explaining the issue | Same |
| Request schema degraded | Endpoint works but skips request body validation | Body-bearing methods (POST, PUT, PATCH) return 500 |
| Media-type example exists | Example is served regardless of schema state | Same |
Common causes: invalid $ref references, unsupported schema constructs, or circular schemas that canât be resolved. Fix the issues reported in the startup banner to restore full behavior.
How accurate is the behavioral classification?
Section titled âHow accurate is the behavioral classification?â96.2% on a 344-endpoint corpus across 11 real-world specs (Stripe, GitHub, Asana, Spotify, and others). Unclassified endpoints fall back to generic behavior â they still return valid schema-based responses, they just donât get CRUD-specific behavior in stateful mode.