Troubleshooting

Use this guide when generation, mocking, or MCP flows fail.

Docs Page Issues

Menu Links Not Loading

• Confirm docs route exists and accepts optional slug.
• Confirm markdown file name matches configured slug mapping.

On This Page Is Empty

• Ensure page contains H2 or H3 headings.
• Ensure markdown rendered successfully.

Data Generation Issues

Schema Parse Fails

• Validate SQL syntax and table definitions.
• Remove unsupported or malformed statements.

Generation Stops Early

• Check queue worker status.
• Check plan limits and current usage.
• Review app logs for specific exceptions.

Relationships Look Wrong

• Re-check parent-child mapping.
• Confirm foreign key columns and compatible data types.
• Click Regenerate in the Relationships panel to re-read foreign keys from your SQL, including ALTER TABLE constraints from pg_dump.
• Ask the Data Assistant to add missing relationships or remove wrong ones.

"References …, Which Is Not Selected for Generation"

A required foreign key points at a table that isn't being generated. Select the parent table too, or make the column nullable.

"Depend on Each Other (Circular Foreign Keys)"

Two tables require each other. Make one of the foreign key columns nullable, or remove one relationship.

Fewer Rows Than Requested

• A one-to-one child can't have more rows than its parent.
• A table with a multi-column unique key can't exceed the number of possible combinations.
• The progress message names the table and the limit. See Relationships and Integrity.

Insert Fails With a Foreign Key Violation

• Regenerate after fixing relationships; older data was generated with the old settings.
• Import the whole export in file order: tables are listed parents first.
• If you push with the CLI, update it to the latest version.

Insert Fails With a Duplicate Key

• Regenerate: unique, one-to-one and multi-column unique keys are enforced on new runs.
• If the constraint isn't in your uploaded SQL, add it to the schema and re-upload, so it can be enforced.

Values Look Generic

• Ask the Data Assistant to adjust the column, or regenerate with additional context about your domain.
• See Realistic Values.

Data Assistant Issues

No Reply Appears

• Check the queue worker and Reverb are running; replies stream over WebSockets.
• Check your AI token usage in Limits and Plans.

A Change Didn't Show Up in the Data

Profile, relationship and row-count changes apply on the next regeneration.

API Mocking Issues

Endpoint Not Matching

• Verify method and path exactly match request.
• Confirm endpoint is active.

Wrong Scenario Returned

• Inspect request conditions and priority: scenarios are tried highest priority first, and all conditions must match.
• Verify fallback/default scenario behavior.
• Use Try it on the mock page (or ask the Mock Assistant to test the request): it shows which scenario matched and why.

Delays Not Applied

• Confirm delay configured on active scenario.

MCP Issues

Unauthorized

If you signed in with OAuth:

• Sign in again from your agent (for example reconnect the Claude connector, run /mcp in Claude Code, codex mcp login fakerforge, or opencode mcp auth fakerforge).
• Check that the app is still listed under Connected apps on the MCP token page. Revoked apps must sign in again.

If you use an API token:

• Confirm token exists and is active.
• Confirm token has fakerforge:generate ability.
• Verify Authorization header format: Authorization: Bearer YOUR_TOKEN.

Sign-In Window Does Not Return to the Agent

• Log in to Faker Forge in the same browser first, then retry the connection.
• Allow pop-ups for fakerforge.com and for your agent's site (for example claude.ai).
• For agents that run on your computer (Claude Code, Codex, OpenCode), keep the agent running until your browser shows that sign-in succeeded; the agent receives the result on a local port.

Agent Never Opens a Sign-In Page

• The agent may not support MCP OAuth. Create a token on the MCP token page and add it as an Authorization: Bearer header instead.

Tool Timeout

• Retry read-only tools first.
• For long operations, expect polling delay windows.

"Ask the User to Confirm This Change First"

manage-relationship needs confirmed: true for updates and removals, sent only after the user agrees.

Inconsistent Reuse

• Re-check codebase_identifier consistency.
• Ensure identifier source does not change across runs.

Recovery Pattern

1. Reproduce with smallest valid input.
2. Validate auth and limits.
3. Run read-only MCP checks.
4. Retry mutation with explicit parameters.
5. Inspect logs/events for exact failure point.

Getting Help

If you are still stuck, email [email protected] with what you tried, the agent or page you used, and any error message. For general or business enquiries, email [email protected].