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 has an active mapping (OFF_FIELD, FAKE, or CONST). 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: No data imported

The table exists in the model but has no underlying data in MongoDB. This occurs when the table was created but no import job was executed against the associated dataset.

Resolution:

1. Open the workspace and navigate to the table in question.
2. Check whether the table has a dataset assigned under Data Sources.
3. If a dataset is assigned, verify that the import job completed successfully. A failed or interrupted import leaves the collection empty.
4. Re-run the import if necessary and confirm that the record count is greater than zero.

Cause 2: All attributes unmapped

Every attribute on the table lacks a data source mapping. When no attribute has a configured mapping, the runtime has no fields to project and returns empty results.

Resolution:

1. Open the table's attribute list.
2. Verify that at least one attribute has a mapping type set (OFF_FIELD, FAKE, or CONST).
3. Assign mappings where missing. See Data Sources & Field Mapping for guidance on selecting the appropriate mapping type.

Cause 3: Filter too restrictive

A filter expression in the query eliminates all records. This is common when filtering on a field whose values do not match the specified criteria.

Resolution:

1. Remove all filter arguments from the query and execute it. If results appear, the filter is the cause.
2. Re-add filter expressions one at a time to identify which condition eliminates the results.
3. Verify that the filter value and operator match the data type and actual values in the dataset. 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, and a mismatched slug returns empty results or a 404 error.

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.

---

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. Assign a mapping type: OFF_FIELD for a real dataset field, FAKE for generated data, or CONST for a fixed value.
3. Check the preview panel for unmapped-attribute hints — these identify exactly which attributes lack mappings.

ts-02-unmapped-hintMissing

Preview hint indicating an unmapped attribute that resolves to null.

Cause 2: OFF_FIELD mapping points to an empty dataset field

The attribute is mapped to a dataset field via OFF_FIELD, but that field 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 dataset field is selected.
2. Check the dataset metadata to verify that the field contains values. Fields with low coverage are indicated in the dataset browser.
3. If the field is sparse, consider switching to a FAKE mapping as an alternative, or select a different dataset field with better coverage.

Cause 3: FAKE generator misconfigured

A FAKE mapping is assigned, but the Faker generator reference is invalid or produces values incompatible with the attribute type.

Resolution:

1. Open the attribute mapping and verify the Faker generator name.
2. Ensure the generator exists in the Faker library and produces the expected data type (e.g., a numeric attribute should not use a name generator).
3. Use the preview panel to test the output of the selected generator.

---

Empty Relations

Symptom: A query requests nested related data (e.g., orders { items { ... } }), 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 entity has no data

The related entity exists in the model but its underlying collection is empty — no data has been imported.

Resolution:

1. Navigate to the target table and verify that it contains imported data.
2. Run an import job for the target entity's dataset if the collection is empty.

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 a sort argument to a query has no visible effect on result ordering.

Cause 1: Field not marked as sortable

Only attributes with the sortable flag enabled can be used as sort fields. Specifying a non-sortable field in the sort argument is silently ignored.

Resolution:

1. Open the attribute in the workspace editor.
2. Enable the sortable flag under API Design.
3. Re-execute the query.

Cause 2: Incorrect field name

The sort argument references a field name that does not match any attribute on the queried entity. Field names are case-sensitive and must match the GraphQL schema exactly.

Resolution:

1. Inspect the entity's attribute list to confirm the exact field name.
2. Correct the sort argument to match the attribute name as defined in the model.

Cause 3: Type incompatibility

Sorting a string field that contains numeric values produces lexicographic ordering (e.g., "9" appears after "10"). This is not a bug — it reflects the attribute's declared type.

Resolution:

1. If numeric ordering is required, ensure the attribute type is set to a numeric type (Integer or Float), not String.
2. Adjust the attribute type in the workspace editor if the underlying data supports it.

---

Filter Returns Everything

Symptom: A filter argument is present in the query, but results are not narrowed — the full dataset is returned.

Cause 1: Field not marked as filterable

Only attributes with the filterable flag enabled participate in filter evaluation. Filter expressions on non-filterable fields are silently ignored.

Resolution:

1. Open the attribute in the workspace editor.
2. Enable the filterable flag under API Design.
3. Re-execute the query with the filter argument.

Cause 2: Wrong operator for type

The filter uses an operator that is incompatible with the field type. For example, applying a CONTAINS operator to a numeric field has no effect.

Resolution:

1. Verify the field type (String, Integer, Float, Boolean, etc.).
2. Select an operator that is valid for that type. String fields support CONTAINS, STARTS_WITH, and EQUALS; numeric fields support EQUALS, GT, GTE, LT, and LTE.
3. Consult the Runtime documentation for the full operator reference.

Cause 3: Value format mismatch

The filter value does not match the expected format. For example, filtering an integer field with a string value ("42" instead of 42) may cause the comparison to fail silently.

Resolution:

1. Ensure the filter value matches the field's declared type.
2. For numeric fields, pass numeric values without quotes. For string fields, pass string values.

---

Authentication Errors (401, 403)

Symptom: The API returns 401 Unauthorized or 403 Forbidden when executing a query.

Cause 1: Missing API key

Private endpoints (Professional plan and above) require an API key in the request headers. Public endpoints (Quick and Free) do not require authentication.

Resolution:

1. Determine whether the project endpoint is public or private. See Account and Plans for plan-level endpoint visibility.
2. If the endpoint is private, include the API key in the Authorization header: Authorization: Bearer <api-key>.
3. Generate or retrieve the API key from the project settings in the workspace.

Cause 2: Expired or invalid actor token

Business and Enterprise plans use actor tokens (X-Actor-Token) to identify individual consumers. An expired or malformed token results in a 401 response.

Resolution:

1. Verify that the X-Actor-Token header is present and contains a valid token.
2. Request a new actor token if the current one has expired.
3. Refer to the Integrators guide for token lifecycle details.

Cause 3: Session limit reached

Your plan's concurrent session limit has been exceeded. Additional authentication attempts are rejected until an existing session expires.

Resolution:

1. Check the session limits for your plan under Account and Plans.
2. Wait for an existing session to expire, or sign out from another device or browser.

Cause 4: 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 and actor tokens.
2. Adjust the request URL accordingly. See Integrators for endpoint details.

---

Rate Limiting (429)

Symptom: The API returns 429 Too Many Requests.

Cause: Plan request limit exceeded

Each plan has a defined request quota (per day for Free, per month for paid plans). Additionally, public endpoints enforce per-IP rate limiting to prevent abuse.

Resolution:

1. Check the Retry-After header in the 429 response to determine when requests will be accepted again.
2. Reduce request frequency or batch queries where possible.
3. If you consistently reach the limit, consider upgrading to a higher plan with a larger request quota. See Account and Plans for plan comparison.

---

Import Failures

Symptom: A data import job does not complete, or the imported data is missing or incomplete.

Cause 1: Dataset format issues

The source dataset contains structural inconsistencies — unexpected field types, encoding problems, or missing metadata fields.

Resolution:

1. Check the import job's progress stream for error messages (visible as SSE events in the workspace).
2. Verify that the dataset has a valid .meta.json sidecar with correct field definitions.

Cause 2: Import job interrupted

The import was interrupted by a network disconnection, browser tab closure, or server timeout.

Resolution:

1. Check the import job status in the workspace. A job stuck in a non-terminal state indicates an interruption.
2. Re-trigger the import — the system overwrites partial data with a fresh import.

Cause 3: Metadata mismatch

The dataset metadata describes fields that do not exist in the actual data, or field types do not match. This causes the import to skip records or fields silently.

Resolution:

1. Compare .meta.json field definitions against the actual dataset content.
2. Regenerate metadata if discrepancies are found, then re-import.

---

Export Issues

Symptom: The generated code from an export does not compile, is incomplete, or contains unresolved placeholders.

Cause 1: Unresolved model hints

The model contains preview hints indicating configuration issues (unmapped attributes, broken relations, missing types). Export proceeds despite hints, but the generated code may be incomplete or incorrect.

Resolution:

1. Open the preview panel and resolve all outstanding hints before exporting.
2. Focus on hints related to unmapped attributes and invalid relations — these directly affect code generation quality.
3. Re-export after all hints are resolved.

Cause 2: Missing required fields

Entities in the model lack attributes that the code generator considers mandatory (e.g., a primary identifier). The generated code may contain placeholder types or fail type checks.

Resolution:

1. Review each entity for completeness. Every entity should have at minimum an identifier attribute.
2. Add any missing attributes and assign appropriate types.

Cause 3: Relation misconfiguration

Relations with incorrect cardinality, missing linking columns, or circular dependencies produce invalid entity definitions in the generated code.

Resolution:

1. Review all relations in the Relations panel. Ensure each relation has valid linking columns on both sides.
2. Test the relations in the runtime preview before exporting — if a relation works correctly at runtime, it will generate correctly.
3. See Export for details on how relations translate to generated code.

---

Preview Shows Stale Data

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

Cause 1: Browser cache

The browser is serving a cached version of the preview response. 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.

Cause 2: Schema regeneration delay

After modifying table attributes, relations, or API design settings, the GraphQL schema requires a brief regeneration period. Queries executed during this window may return results based on the previous schema.

Resolution:

1. Wait a few seconds after making model changes before executing a preview query.
2. If the schema still appears outdated, navigate away from the preview and return — this forces a fresh schema fetch.

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	No data imported	Run import job for the dataset	Data Sources
Query returns empty array	All attributes unmapped	Assign mappings to attributes	Data Sources
Query returns empty array	Wrong project slug	Verify slug in project settings	Runtime
Field returns null	Attribute has no mapping	Assign OFF_FIELD, FAKE, or CONST mapping	Data Sources
Field returns null	OFF_FIELD points to sparse field	Switch mapping or select different field	Data Sources
Nested relation returns []	Relation direction inverted	Correct direction in relation editor	Relations
Nested relation returns []	Target entity has no data	Import data for the target entity	Data Sources
Nested relation returns []	Linking columns incorrect	Verify column references on both sides	Relations
Sort has no effect	Field not marked sortable	Enable sortable flag on the attribute	API Design
Filter has no effect	Field not marked filterable	Enable filterable flag on the attribute	API Design
Filter has no effect	Operator/type mismatch	Use operator compatible with field type	Runtime
401 Unauthorized	Missing API key	Add Authorization: Bearer <key> header	Integrators
401 Unauthorized	Expired actor token	Request a new actor token	Integrators
403 Forbidden	Session limit reached	Wait for session expiry or sign out elsewhere	Account
429 Too Many Requests	Plan rate limit exceeded	Wait for Retry-After period or upgrade plan	Account
Import incomplete	Job interrupted	Re-trigger import from workspace	Data Sources
Export doesn't compile	Unresolved model hints	Resolve all hints before exporting	Preview & Hints
Preview shows old data	Browser cache	Hard refresh (Ctrl+Shift+R / Cmd+Shift+R)	Preview & Hints