Skip to content
Published beta · latest tagRead as Markdown

Error codes ​

Mimlet errors that callers may need to handle carry a stable code. Branch on the error class or its code, never on the message: message wording, stack traces and cause chains can change. The stability contract treats these codes as machine-readable API. New codes may be added; existing codes keep their meaning. CLI reports use a separate set of diagnostic codes.

Some guards are plain TypeErrors without a code, for example a missing session for Effect or Faker builders, or loading @mimlet/effect with Effect 3. Treat those as programming errors, not states to branch on.

Core (@mimlet/core) ​

ClassCodeWhen
BuilderValidationErrorVALIDATION_FAILEDA validated build was rejected by its schema. The validator's issues are on the non-enumerable issues property.
BuilderGenerationErrorGENERATION_FAILEDGeneration could not produce a value, for example a selected union variant that does not satisfy the enclosing union.
BuilderPathErrorINVALID_BUILDER_PATHA typed path operation received a path that does not exist on the value, or a fluent() path setter found no parent. Extends TypeError.
FixtureCaptureErrorUNSUPPORTED_FIXTURECapture met a value it cannot record, such as a class instance, function, accessor, promise or weak collection.
CAPTURE_LIMITCapture exceeded its size or depth budget.
INVALID_CAPTUREA capture record being restored is malformed or uses an unsupported format.
ScenarioErrorSCENARIO_DEFINITIONA scenario definition is invalid. The error names the node.
SCENARIO_CONFLICTA trait was applied twice, or conflicts with an existing node override.
SCENARIO_EXECUTIONA scenario node failed while building. The message names the node, the step and the cause's message; the original error is the cause.
SessionBudgetErrorSESSION_BUDGET_EXHAUSTEDA generation session ran out of its operation, tracked-key, unique-value or uniqueness-attempt budget.
SessionReplayErrorINVALID_SESSION_REPLAYA session replay is malformed, or its fingerprint, provider/version or configuration does not match.

A BuilderValidationError message names the issue count and up to three failing paths, for example Schema validation failed: 2 issues at owner.email, items[0].price. When an adapter reports an error thrown inside a schema callback, the message ends with where it came from, for example ; thrown by the Zod transform fromDto. It never includes native issue messages, which can repeat the rejected value. Read the non-enumerable issues property, or call formatValidationIssues(error, { messages: true }), to see them. See validation diagnostics.

A SCENARIO_EXECUTION message names the node, where it failed and the first 200 characters of the cause's message on one line, for example Scenario node "deal" failed in patch 1: A patch of deal returned a plain object .... A fluent() path setter's BuilderPathError names the setter, the path and the missing parent, for example withLimit() cannot set pagination.limit: pagination is missing; .... The path setter's message names keys only. The scenario message repeats the cause's message, so an error your own code throws appears as written; Mimlet's own errors keep fixture values out of their messages.

Adapters and schema packages ​

PackageClassCodeWhen
@mimlet/adapterAdapterDefinitionErrorINVALID_ADAPTER_DEFINITIONdefineAdapter received invalid metadata or operations. Extends TypeError.
@mimlet/json-schemaSchemaPreparationErrorSCHEMA_PREPARATION_FAILEDA schema or a reference it uses could not be prepared for generation.
SchemaGenerationErrorSCHEMA_GENERATION_FAILEDBounded generation could not produce a valid value. This does not prove none exists.
NegativeCaseErrorNEGATIVE_CASE_MISMATCHA negative case did not fail validation with the expected number of issues.
@mimlet/fakerFakerSessionErrorFAKER_SESSION_RECONFIGURATIONCode tried to reseed a session-scoped Faker instance; create or restore a session instead.
@mimlet/fast-checkPropertyIntegrationErrorPROPERTY_CONFIGURATIONA property check is misconfigured, for example without a fingerprint and provider/version.
PROPERTY_REPLAYA property replay's version, engine, identity or path does not match.
FixturePropertyErrorPROPERTY_FAILEDA fixture property failed; its report getter holds the counterexample and replay record.

SchemaPreparationError.schemaPath locates the problem. When it is inside a supplied reference, reference names that reference and the path is relative to it. When a $ref resolves to nothing, missingReference names the target and schemaPath points at the $ref. References the schema does not reach are not prepared.

@mimlet/zod throws the same SchemaPreparationError on the first build of a fromZod() builder when Zod cannot convert the schema's input to JSON Schema, for example for z.date(). schemaPath then points into the converted input schema, and cause is Zod's error.

Protocol packages ​

PackageClassCodeWhen
@mimlet/apiApiContractErrorAPI_CONTRACT_FAILEDAn OpenAPI or AsyncAPI document, operation or message cannot be used.
@mimlet/graphqlGraphQLFixtureErrorGRAPHQL_FIXTURE_FAILEDA GraphQL schema, operation or output type cannot be generated.
@mimlet/protobufProtobufFixtureErrorPROTOBUF_FIXTURE_FAILEDA Protobuf schema could not be prepared, or a message failed to decode.
@mimlet/avroAvroFixtureErrorAVRO_FIXTURE_FAILEDAn Avro schema failed to compile or a value does not fit it; the error carries the path.

A GraphQLFixtureError for a missing custom-scalar hook names the scalar, and schema or operation validation issues keep GraphQL's message. A ProtobufFixtureError for a missing import names the imports key to add.

Tooling ​

PackageClassCodeWhen
@mimlet/codegenCodegenErrorCODEGEN_FAILEDGeneration arguments or configuration are invalid, or output could not be emitted.
@mimlet/playgroundPlaygroundErrorINVALID_REQUESTThe playground received a malformed generation request.
GENERATION_TIMEOUTGeneration exceeded its time budget.
GENERATION_ABORTEDGeneration was cancelled.
GENERATION_FAILEDGeneration failed in the playground's child process.

Mimlet · beta · MIT licensed