Error Codes

Every error mockingpug throws extends a single MockingpugError base class and carries a stable code (MP-<CATEGORY>-<NNN>), so your code (or a human reading a log) can reliably tell "this is an expected/documented failure" apart from "something broke inside mockingpug." Codes never change meaning between versions: new codes get new numbers, existing ones are never reused for something else.

Each error also carries, where relevant, a location ({ file, path } pointing at the offending schema file/field) and a hint (a short, actionable suggestion, often a "did you mean" typo correction).

`MP-SCHEMA-*`: invalid schema DSL

Thrown while parsing mock/api/**/schema.json / mock/data/*.json.

Code	Cause
`MP-SCHEMA-001`	Unrecognized generator type (e.g. `emial[gmail.com]`), comes with a "did you mean" suggestion.
`MP-SCHEMA-004`	Failed to read a schema/custom-dictionary file (I/O error).
`MP-SCHEMA-005`	The file's content isn't valid JSON.
`MP-SCHEMA-006`	The schema file's root isn't a JSON object.
`MP-SCHEMA-007`	`"amount"` is missing, non-numeric, or negative.
`MP-SCHEMA-008`	`"data"` is missing or isn't an object.
`MP-SCHEMA-009`	A field's DSL value isn't a string.
`MP-SCHEMA-010`	A custom dictionary file's content isn't a JSON array.
`MP-SCHEMA-011`	Two schema files resolve to the same entity name (folder name collision).
`MP-SCHEMA-012`	`"bypass"` is present but not a boolean.
`MP-SCHEMA-013`	`"fixtures"` is present but isn't an array of objects.
`MP-SCHEMA-014`	`"fixtures"` has more entries than `"amount"`.
`MP-SCHEMA-015`	`"slugify[...]"` isn't exactly two comma-separated parts (a field name and a separator).
`MP-SCHEMA-016`	A `"slugify[field,...]"` references a field that doesn't exist on the same entity.
`MP-SCHEMA-017`	A `"slugify[field,...]"` references a field declared at the same position or later in `data` (including a self-reference).
`MP-SCHEMA-018`	`"literal"` is present but isn't an array of objects.
`MP-SCHEMA-019`	`"literal"` has more entries than `"amount"`.
`MP-SCHEMA-020`	A multi-pick `"data.<entity>.[...]"` lists fewer than two fields, an invalid field name, or the same field twice.
`MP-SCHEMA-021`	Two fields on the same entity produce the same output field name (a multi-pick's projected name collides with another declared/projected field).
`MP-SCHEMA-022`	An `array[...]` item is a bare or multi-pick `crossRef`; only a field-level pick (`array[data.<entity>.<field>].N`) is a valid array item.
`MP-SCHEMA-023`	A conditional field's `{when,then,else}` object is malformed: `"when"` isn't a non-empty object of literal values, or `"then"`/`"else"` is missing.
`MP-SCHEMA-024`	A conditional field's `"then"`/`"else"` has an unsupported raw type — must be a DSL string, a JSON literal (`null`/boolean/number), or a nested `{when,then,else}` object.
`MP-SCHEMA-025`	A conditional field's `"then"`/`"else"` resolved to a bare relation or multi-pick `crossRef`, neither of which produces one concrete value for a single branch.
`MP-SCHEMA-026`	A conditional field's `"when"` references a field that doesn't exist on the same entity.
`MP-SCHEMA-027`	A conditional field's `"when"` references a field declared at the same position or later in `data` (including a self-reference).

`MP-DEP-*`: cross-entity reference graph

Thrown while validating data.* references across all schemas (before any generation happens).

Code	Cause
`MP-DEP-001`	A `data.<entity>(.field)` reference points at an entity with no schema, comes with a "did you mean" suggestion against known entity names.
`MP-DEP-002`	An unresolvable field-level reference cycle (A needs B's field, B needs A's field).
`MP-DEP-003`	A bare relation (`data.<entity>`, no field) has no matching back-reference in the target schema.
`MP-DEP-004`	A bare relation's target schema has more than one field-level reference back, so it's ambiguous: mockingpug won't guess which one is the real foreign key.

`MP-GEN-*`: generation-time failures

Code	Cause
`MP-GEN-000`	Internal exhaustiveness guard, should be unreachable for any valid schema; report it as a bug if you see it.
`MP-GEN-001`	A `crossRef` field reached the low-level value generator directly instead of going through the dependency-graph resolver. A single-level `array[data.<entity>.<field>].N` is supported (handled before reaching here); a bare/multi-pick array item is rejected earlier at parse time (`MP-SCHEMA-022`); a nested array of `crossRef` items isn't supported yet (see Schema DSL → Arrays). Everywhere else it's an internal invariant violation, report it as a bug.
`MP-GEN-002` / `MP-GEN-003`	A custom dictionary is empty, or every entry has already hit its `max` cap and there's nothing left to pick from.
`MP-GEN-004` / `MP-GEN-005`	A field-level reference (`data.user.id`) couldn't resolve because the target entity has zero generated records, or the referenced field doesn't exist on it.
`MP-GEN-006`	A `slugify` field reached the low-level value generator directly instead of going through `recordGenerator.ts`. Same `array[slugify[...]].N` caveat as `MP-GEN-001` applies; everywhere else it's an internal invariant violation, report it as a bug.
`MP-GEN-007`	A `slugify` field's source field is missing or not a string on the record being generated (shouldn't happen for a schema that passed `MP-SCHEMA-016`/`017` validation).
`MP-GEN-008`	A `conditional` field (`{when,then,else}`) reached the low-level value generator directly instead of going through `recordGenerator.ts`, where the sibling record needed to evaluate `"when"` is available — an internal invariant violation, report it as a bug.

`MP-STORE-*`: persistent store failures

Code	Cause
`MP-STORE-001`	A store file on disk contains invalid JSON (corrupted `.mockingpug/db/<entity>.json`). Fix: delete the file or run `mpug reset`.
`MP-STORE-002`	Failed to write a store file (disk/permission error).
`MP-STORE-003`	An unsafe entity name was rejected before it could be used to build a file path, a path-traversal guard, not expected to trigger from a normal schema.
`MP-STORE-004`	Failed to read a store file, or list the store directory (I/O error).

`MP-CONFIG-*`: invalid `mock.config.js`

Code	Cause
`MP-CONFIG-001`	The config file doesn't export an object.
`MP-CONFIG-002`	`"dir"` isn't a string.
`MP-CONFIG-003`	`"seed"` isn't a string or number.
`MP-CONFIG-004`	`"persist"` isn't an object.
`MP-CONFIG-005`	`"persist.adapter"` isn't `'file'`/`'memory'`.
`MP-CONFIG-006`	`"persist.strategy"` isn't `'always'`/`'fresh'`.
`MP-CONFIG-007`	The config file itself threw while being loaded (syntax error, etc).
`MP-CONFIG-008`	`"baseUrl"` isn't a string.
`MP-CONFIG-009`	`"pagination"` isn't an object.
`MP-CONFIG-010`	`"pagination.strategy"` isn't one of `page`/`offset`/`cursor`/`false`.
`MP-CONFIG-011`	`"pagination.defaultLimit"` isn't a positive number.
`MP-CONFIG-012`	`"pagination.maxLimit"` isn't a positive number.
`MP-CONFIG-013`	`"pagination.params"` isn't an object.
`MP-CONFIG-014`	`"limits"` isn't an object.
`MP-CONFIG-015`	`"limits.maxAmount"` isn't a positive number.
`MP-CONFIG-016`	`"limits.maxArrayDepth"` isn't a positive number.
`MP-CONFIG-017`	`"runtime"` isn't an object.
`MP-CONFIG-018`	`"runtime.errorRate"` isn't a number in `[0, 1]`.
`MP-CONFIG-019`	`"runtime.delay"` isn't a non-negative number.
`MP-CONFIG-020`	`"docs"` isn't an object.
`MP-CONFIG-021`	`"docs.enabled"` isn't a boolean.
`MP-CONFIG-022`	`"target"` isn't a string.

`MP-REQ-*`: expected request-level failures

Not bugs: the normal REST-ish 4xx path, returned as { error: { code, message } } in the response body.

Code	HTTP status	Cause
`MP-REQ-001`	404	Unknown entity/route: nothing matches the requested path.
`MP-REQ-002`	404	The entity exists, but no record with that `id` was found.
`MP-REQ-003`	404	A `one` endpoint's `where` matched no record.
`MP-REQ-006`	501	A `handler` route (your own code) isn't wired up.

`MP-ROUTE-*`: invalid endpoints (`doctor`)

Reported by mpug doctor when a route in mock/routes/** doesn't line up with its tables. See Endpoints.

Code	Cause
`MP-ROUTE-001..006`	Malformed route file: not an object, bad `kind`, missing `id`/`path`/`method`, or a missing kind-specific field.
`MP-ROUTE-010`	Two routes answer the same `method` + `path`.
`MP-ROUTE-011`	`from` references a table that doesn't exist.
`MP-ROUTE-012`	A `where` field doesn't exist, or binds a `:param` the path doesn't have.
`MP-ROUTE-013`	A `select` field (or dotted path) doesn't exist on the table.
`MP-ROUTE-014`	An `include` points at a non-relation field or unknown reverse table/field.
`MP-ROUTE-015`	A `mutation`'s `body`/`response` isn't valid JSON.
`MP-ROUTE-016`	A path `:param` is never used in `where`.
`MP-ROUTE-017`	A `paginate` limit isn't a positive integer.
`MP-ROUTE-018`	A `sort` field doesn't exist on the table.
`MP-ROUTE-019`	An `action` uses `$ref.<name>` before any effect named `<name>` ran.

Code	Cause
`CLOUD-AUTH`	Missing/revoked token — run `mockingpug login`.
`CLOUD-PROJECT`	Project not found.
`CLOUD-VERSION`	Requested version doesn't exist / nothing published.
`CLOUD-LIMIT`	Connected-apps limit reached.
`CLOUD-FORBIDDEN`	Push needs an edit-schema token (a CI token can only pull).
`CLOUD-BUSY`	The project is open in the cloud editor — close it and retry.
`CLOUD-REQUEST`	Bad request / an unsafe artifact name in the cloud response.

Anything without an `MP-*` code

If a caught error doesn't carry one of the codes above, it's treated as a genuine bug inside mockingpug, not a project misconfiguration. The CLI prints its full stack trace (unexpected internal error:) instead of a clean one-liner, and transport adapters (react/next) log it in full to the server/devtools console while the client only ever sees a generic 500 with no internal detail.

Error Codes

On this page