Help
Troubleshooting
Fix the most common docs, generation, mocking, and MCP issues.
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.
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.
- Verify fallback/default scenario behavior.
Delays Not Applied
- Confirm delay configured on active scenario.
MCP Issues
Unauthorized
- Confirm token exists and is active.
- Confirm token has fakerforge:generate ability.
- Verify Authorization header format.
Tool Timeout
- Retry read-only tools first.
- For long operations, expect polling delay windows.
Inconsistent Reuse
- Re-check codebase_identifier consistency.
- Ensure identifier source does not change across runs.
Recovery Pattern
- Reproduce with smallest valid input.
- Validate auth and limits.
- Run read-only MCP checks.
- Retry mutation with explicit parameters.
- Inspect logs/events for exact failure point.