Troubleshooting

A systematic guide to diagnosing and resolving common issues encountered while working with Mockomat. Each section describes an observable symptom, its likely causes, and step-by-step resolution procedures.

Diagnostic Approach

When a query or workflow behaves unexpectedly, inspect the following areas in order. Most issues originate in the first two layers; proceeding through the full list ensures nothing is overlooked.

1. Table and attribute definitions — verify that the entity exists, attributes are present, and types are correct. See Tables & Attributes.
2. Endpoint and query metadata — confirm that the endpoint is configured and the query structure matches the schema. See API Design.
3. Source mapping state — check that every attribute that must carry values is bound to a column of the imported data (SOURCE mapping) or holds a CONSTANT value, which appears on every row; COMPUTED expressions are not evaluated. See Data Sources & Field Mapping.
4. Relation configuration — verify direction, cardinality, and linking columns for all relations. See Relations.
5. Plan limits and authentication — confirm that your plan permits the operation and that credentials are valid. See Account and Plans.

ts-01-diagnostic-flowMissing

Recommended diagnostic flow: model → API → mapping → relations → auth.

---

Empty Responses

Symptom: A query returns an empty array or no records, despite the expectation that data should be present.

Cause 1: The table is not bound to imported data

The table exists in the model but is not bound to a table of Mockomat's data pool, or none of its attributes is bound to a column. The runtime then has nothing to read: it answers with an empty list and a NOT_READY error saying the table is not bound to imported data. The runtime preview shows Not mapped to imported data for it.

Resolution:

1. Open the Mappings pane of the modelling board for the table.
2. Bind the table to a table of the data pool, then bind its attributes to columns (SOURCE mappings).
3. Run the query again. See Data Sources & Field Mapping.

Cause 2: The selected variant holds no rows

The table is bound, but the variant chosen in the Mappings pane holds no rows.

Resolution:

1. Open the Mappings pane and check the selected variant.
2. Choose All variants or a variant that holds rows.

Cause 3: Parameters too restrictive

A parameter or scope filter of the operation eliminates all records.

Resolution:

1. Run the query without parameters. If results appear, a parameter is the cause.
2. Add parameters back one at a time to find the condition that removes the results.
3. Check that the value and operator match the actual values in the data. Pass values in the type the data holds — numbers without quotes, booleans as true or false. Use the preview panel to inspect sample data.

Cause 4: Wrong project slug

The query targets an incorrect project endpoint. Each project has a unique slug; an unknown slug answers 404 PROJECT_NOT_FOUND.

Resolution:

1. Confirm the project slug in the workspace header or project settings.
2. Verify that the request URL follows the pattern POST /mock/{slug}/graphql with the correct slug. See Runtime for endpoint details.
3. Check that the API key belongs to this project — a key of another project gets the same 404.

---

Null Fields

Symptom: A query returns records, but specific fields contain null values where data is expected.

Cause 1: No mapping configured

The attribute exists in the model but has no data source mapping assigned. Unmapped attributes always resolve to null.

Resolution:

1. Open the attribute in the workspace editor.
2. Bind the attribute to a column of the imported data (SOURCE mapping), or give it a CONSTANT value, which the runtime returns on every row. A COMPUTED expression is not evaluated.
3. The Mappings pane shows which attributes are still open (not bound).

ts-02-unmapped-hintMissing

Preview hint indicating an unmapped attribute that resolves to null.

Cause 2: SOURCE mapping points to an empty dataset column

The attribute is bound to a dataset column via SOURCE, but that column contains no values for the imported records. This can happen when the source dataset has sparse or incomplete coverage for certain fields.

Resolution:

1. Open the attribute mapping and note which column is bound.
2. Check sample values in the runtime preview to see whether the column holds values for these records.
3. If the column is sparse, bind a different column with better coverage.

Cause 3: COMPUTED mapping

The attribute has a COMPUTED mapping. The runtime does not evaluate expressions, so a computed field is not part of the response.

Resolution:

1. Open the attribute mapping and check its type.
2. If the field must carry values, bind it to a column of the imported data (SOURCE mapping), or give it a CONSTANT value, which the runtime returns on every row.
3. Use the preview panel to confirm that the field now returns values.

---

Empty Relations

Symptom: A query requests nested related data (e.g., orders { id totalAmount } inside each customer), but the nested field returns an empty array or null.

Cause 1: Relation direction is inverted

The relation is defined in the wrong direction. A one-to-many relation from Order to OrderItem requires the foreign key on OrderItem, not on Order. If the direction is reversed, the runtime cannot resolve the lookup.

Resolution:

1. Open the Relations configuration for the affected relation.
2. Verify that the source entity, target entity, and direction match the intended data flow.
3. Correct the direction if necessary. The entity that holds the foreign key should be the "many" side.

Cause 2: Target table is not bound to imported data

The related table exists in the model but is not bound to the data pool, so there are no rows to nest.

Resolution:

1. Open the target table in the Mappings pane and bind it to a table of the data pool.
2. Check the target table in the runtime preview: it must return rows on its own.

Cause 3: Linking columns are incorrect

The foreign key or linking column references do not match between the two entities. This causes the lookup stage to find no matching records.

Resolution:

1. Open the relation configuration and verify the linking column on each side.
2. Confirm that the linking column on the source side contains values that exist in the target side's referenced column.
3. Use the preview panel to inspect sample values from both columns and verify that they overlap.

ts-03-relation-configMissing

Relation editor showing source entity, target entity, and linking columns.

Cause 4: Cardinality mismatch

The relation is configured as one-to-one but the data represents a one-to-many relationship, or vice versa. This can cause the runtime to return only the first match (or null) when multiple records exist.

Resolution:

1. Review the cardinality setting in the relation configuration.
2. Compare it to the actual data distribution — does the source entity have one or many related records in the target?
3. Adjust the cardinality to match the data structure.

---

Sort Not Working

Symptom: Adding sortField and sortDirection to a list query has no visible effect on result ordering.

Cause 1: sortField does not name a mapped attribute

sortField must be the name of an attribute that is bound to a data column (SOURCE mapping). The Sortable flag is not involved — the mock runtime does not read it. A name that matches no mapped attribute leaves the rows in storage order.

Resolution:

1. Inspect the table's attribute list to confirm the exact attribute name. Names are case-sensitive.
2. Make sure the attribute is bound to a column of the imported data.
3. Re-execute the query.

Cause 2: Numbers stored as text

Sorting follows the values as they are stored in the data. A column that stores numbers as text sorts lexicographically (e.g., "9" appears after "10"). Changing the attribute type does not convert the stored values.

Resolution:

1. Check sample values of the column in the runtime preview.
2. If numeric ordering is required, bind the attribute to a column that stores numbers.

---

Filter Returns Everything

Symptom: An argument is present in the query, but results are not narrowed — the full list is returned.

Cause 1: The operation has no parameter for the argument

Filtering uses the parameters you define on an operation in API Design. The Filterable flag is not involved — the mock runtime does not read it. An operation without parameters ignores extra arguments; an operation with parameters rejects unknown arguments with BAD_USER_INPUT.

Resolution:

1. Open the operation in API Design.
2. Add a parameter for the attribute, with the operator you need.
3. Re-execute the query with the parameter's name as argument.

Cause 2: Wrong operator

The parameter's operator does not fit the comparison you want. The operators are eq, neq, gt, gte, lt, lte, in (a list of values) and like (contains, case-insensitive).

Resolution:

1. Check the parameter's operator in API Design.
2. Consult the Runtime documentation for the full operator reference.

Cause 3: Value format mismatch

The value does not match the type stored in the data. For example, a number sent as a string ("42" instead of 42) does not match a numeric column.

Resolution:

1. Pass values in the type the data holds: numbers without quotes, booleans as true or false, text as strings.

---

Authentication Errors (401, 403)

Symptom: The mock API returns 401 Unauthorized or 403 Forbidden instead of data. The JSON body's code names the cause.

Cause 1: Missing API key (UNAUTHENTICATED)

The mock API of every project in an account answers only to an API key of that project — whatever the project's preview share setting. API keys come with the Professional plan and above. A guest project answers to its share token instead.

Resolution:

1. Create a key for the project under Account → API keys.
2. Send it in the Authorization header: Authorization: Bearer mck_… (or in X-API-Key).
3. For a guest project, append the token of its preview share link: ?token=….

Cause 2: Invalid, revoked or expired key (API_KEY_INVALID, API_KEY_EXPIRED)

The key is unknown, was revoked or deleted, or its expiry date has passed.

Resolution:

1. Check the key's status and expiry in the API keys list.
2. Create a new key and replace the old one in your configuration.

Cause 3: Management-only key (API_KEY_SCOPE_INSUFFICIENT, 403)

A key with the Management scope reaches the management API only, never the mock runtime.

Resolution:

1. Use a key with the Runtime or Full scope for mock API calls.

Cause 4: Malformed actor token (ACTOR_TOKEN_INVALID)

Actor tokens (X-Actor-Token) are optional. A token that is sent must be one issued by POST /runtime/actors (format act_…).

Resolution:

1. Request a new actor token with your API key, or leave the X-Actor-Token header out.
2. Refer to the Integrators guide for token lifecycle details.

Cause 5: Wrong endpoint

The request targets the management API (/graphql) instead of the mock runtime API (/mock/{slug}/graphql), or vice versa. These endpoints use different authentication mechanisms.

Resolution:

1. Confirm which API surface you intend to use. The management API requires a JWT session; the mock runtime API uses API keys (actor tokens are optional).
2. Adjust the request URL accordingly. See Integrators for endpoint details.

---

Rate Limiting (429)

Symptom: The API returns 429 Too Many Requests.

Cause 1: Plan request quota used up

Each plan has a request quota: per day on Starter, per calendar month on paid plans. Requests from the in-app preview count as well. When the quota is used up, the mock API answers 429 until it starts again — daily quotas at 00:00 UTC, monthly quotas on the first of the month.

Resolution:

1. Wait until the quota starts again.
2. Reduce request frequency, or cache responses in your application where possible.
3. If you consistently reach the limit, move to a plan with a larger quota or ask our sales team for additional capacity. See Account and Plans.

Cause 2: Per-IP rate limit

The mock API also limits requests per IP address (60 requests per minute). This 429 carries a Retry-After header.

Resolution:

1. Wait for the Retry-After period, then retry.
2. Spread requests over time instead of sending bursts.

---

OpenAPI Import Problems

Symptom: An OpenAPI import is refused or creates fewer tables than expected.

Cause 1: Unsupported specification

Only OpenAPI 3.x and Swagger 2.0 specifications in JSON or YAML are accepted, up to 1 MB.

Resolution:

1. Check the openapi or swagger version field of the file.
2. Convert older or other formats to OpenAPI 3.x before importing.

Cause 2: Schemas not selected or above the limit

Only the schemas you select are imported, up to 50 per import, and the new tables count toward your plan's table limit.

Resolution:

1. Select the schemas you need; import larger specifications in several steps.
2. Check your plan's limits in Account and Plans.

---

Export Issues

Symptom: The generated code from an export is incomplete or behaves differently than the model.

Cause 1: Relations are missing

Code packages do not generate relations between tables yet.

Resolution:

1. Add the relations of your model to the generated entities and services.
2. See Export for what a code package contains.

Cause 2: Required fields accept empty values

The Required flag is not applied in code packages yet; generated fields are optional.

Resolution:

1. Add validation for the fields your application requires.

Cause 3: Code packages are not offered

If the export wizard offers only the OpenAPI specification, code packages are not available in your app yet, your plan does not include them (Professional and above), or your role is below Editor.

Resolution:

1. Export the OpenAPI specification in the meantime.
2. Check your plan and role.

---

Preview Shows Stale Data

Symptom: The preview panel does not reflect changes made to the model or mappings.

Cause: Browser cache

The browser is serving a cached version of the page. This is more common after rapid successive changes.

Resolution:

1. Perform a hard refresh (Ctrl+Shift+R / Cmd+Shift+R) in the browser.
2. If the issue persists, clear the browser cache for the Mockomat domain and reload.

ts-04-preview-staleMissing

Preview panel showing results that do not yet reflect a recent attribute change.

---

Common Issues Quick Reference

Symptom	Likely Cause	Resolution	Reference
Query returns empty array	Table not bound to imported data (NOT_READY)	Bind the table and its attributes in the Mappings pane	Data Sources
Query returns empty array	Selected variant holds no rows	Choose All variants or another variant	Data Sources
Query returns empty array	Wrong project slug	Verify slug in project settings	Runtime
Field returns null	Attribute has no mapping	Bind the attribute to a data column (SOURCE mapping) or give it a CONSTANT value	Data Sources
Field returns null	SOURCE points to a sparse column	Select a column with better coverage	Data Sources
Field returns null	COMPUTED mapping (not evaluated)	Bind the attribute to a data column (SOURCE mapping) or give it a CONSTANT value	Data Sources
Nested relation returns []	Relation direction inverted	Correct direction in relation editor	Relations
Nested relation returns []	Target table not bound to imported data	Bind the target table in the Mappings pane	Data Sources
Nested relation returns []	Linking columns incorrect	Verify column references on both sides	Relations
Sort has no effect	sortField is not a mapped attribute	Use the name of an attribute bound to a data column	Runtime
Filter has no effect	No parameter defined for the argument	Add the parameter to the operation	API Design
Filter has no effect	Value sent in the wrong type	Send numbers without quotes, booleans as true/false	Runtime
401 Unauthorized	Missing, revoked or expired API key	Send a valid key: Authorization: Bearer mck_…	Integrators
401 Unauthorized	Malformed actor token	Request a new actor token or omit X-Actor-Token	Integrators
403 Forbidden	Management-only API key	Use a Runtime or Full key	Integrators
404 Not Found	API key of another project	Use a key of the called project	Integrators
429 Too Many Requests	Plan quota used up	Wait until the quota starts again, or upgrade	Account
429 Too Many Requests	Per-IP rate limit	Wait for the Retry-After period	Integrators
OpenAPI import refused	Unsupported version, or file above 1 MB	Use OpenAPI 3.x or Swagger 2.0 in JSON or YAML	Import
Generated code lacks relations	Relations are not generated yet	Add them in the generated code	Export
Preview shows old data	Browser cache	Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)	Preview & Hints