Feature-Specific Troubleshooting

Troubleshoot issues related to specific modes or functions within Genie.

CODE planning is blocked for the selected model

Symptoms: CODE stops before generation, or Settings warns that the selected planning route is incompatible.
Cause: The selected model route cannot perform the structured planning step CODE needs before generation.
Fix: Open Settings > Models and choose a model route that supports CODE planning, or turn off Use one model and choose a compatible Logistics route.
Note: The Preflight Questions value only controls how many clarification questions can be asked. It does not disable planning.

Symptoms: IDE logs show streamable HTTP invalid_http_request, SSE fallback Non-200 (400), or repeated client connect failures.
Cause: MCP endpoint/path mismatch, missing bearer auth header, or Local MCP Bridge disabled.
Fix:
1. In Settings > Local MCP, confirm Local MCP Bridge is enabled and status is running.
2. Verify your IDE config uses URL path /mcp (not root-only endpoint).
3. Verify Authorization: Bearer <token> is present.
4. Recopy the current setup snippet from Settings > Local MCP.
5. Ensure host/port match Genie (127.0.0.1 + configured port).

Symptoms: Claude Desktop starts but Genie tools/resources do not appear under connectors, or Claude logs show a stdio server exit.
Cause: Claude Desktop cannot consume Genie’s local Streamable HTTP endpoint directly from claude_desktop_config.json; it needs the Claude Desktop stdio bridge snippet.
Fix:
1. In Settings > Local MCP, choose Claude Desktop (stdio bridge).
2. Copy the snippet into Claude Desktop’s developer config.
3. Confirm npx can run mcp-remote@latest.
4. Keep Genie running with Local MCP enabled, then restart Claude Desktop.

Symptoms: Cursor, Codex, Claude, or another MCP client calls genie_stage_script_xml for plain English requests.
Cause: genie_stage_script_xml is only for completed FileMaker XML handoff, or when the user explicitly asks to stage raw XML directly using Genie.
Fix:
1. Ask the agent to call genie_get_capabilities again.
2. For natural-language script creation, use genie_stage_new_script.
3. For natural-language edits to a selected/attached Genie script, use genie_stage_edit_script.
4. Use genie_stage_script_xml only when the request includes a complete fmxmlsnippet.

Symptoms: An MCP client says Genie needs metadata for words like URL, API, JSON, or an external service name such as Asana.
Cause: Metadata preparation is only for concrete FileMaker references. Normal external-service script wording should not be treated as FileMaker metadata.
Fix:
1. Ask the agent to restage the natural-language request with genie_stage_new_script or genie_stage_edit_script.
2. Use genie_prepare_metadata_selection only when the prompt references real FileMaker tables, fields, layouts, scripts, custom functions, or ExecuteSQL schema references.
3. Keep genie_query for read-only SELECT work, not for Insert from URL script generation.

Symptoms: MCP client rejects or filters a tool because of name format.
Cause: Some clients enforce underscore-only naming.
Fix: Use fm_get_fields_on_layout in strict environments.
Note: Genie also accepts alias calls (fm.get_fields_on_layout, fm-get_fields_on_layout) for compatibility, but underscore form is the safest default.

Symptoms: A file save dialog appears, but the file is not written or is empty.
Cause: Missing write permissions for the target folder or a transient error in data generation.
Fix:
1. Re-run the query or chart generation once.
2. Ensure you are choosing a writable local directory (e.g., Documents or Desktop).
3. Verify your computer has sufficient free space.

Symptoms: Chat shows “No active migration plan,” or clicking a migration action does nothing useful.
Cause: The prior plan was cleared, completed, or replaced by a new DATA request.
Fix:
1. Start a fresh DATA request with clear migration intent.
2. Wait for “Migration plan ready (N steps)” before using step actions.
3. Avoid using old action links from earlier messages after starting a new plan.

Symptoms: Chat indicates the current migration step is halted.
Cause: A validation or execution failure stopped progression to protect data integrity.
Fix:
1. Review the failure message shown in chat.
2. Choose Retry Step if the SQL is still correct.
3. Choose Skip Step only if you accept migration inconsistency risk.
4. Choose Abort Plan if the sequence should not continue.

Symptoms: Chat does not offer Execute All, or the action is unavailable for the current DATA response.
Cause: The current pending operation is not part of an active migration plan.
Fix:
1. Use Confirm or Cancel for single-statement DATA execution.
2. If your intent is multi-step, restate the request as a migration sequence.
3. Regenerate and confirm that Genie returns a migration plan before using Execute All.

Symptoms: Genie rejects a confirmation attempt and requests exact full-table wording.
Cause: Full-table or destructive operations require strict confirmation language.
Fix:
1. Re-read the confirmation requirement shown in chat.
2. Use the provided action link or exact required wording.
3. If full-table impact is not intended, cancel and regenerate scoped SQL.

Symptoms: Chat shows a placeholder/parameter mismatch block and execution does not start.
Cause: SQL placeholder count does not match supplied parameters.
Fix:
1. Regenerate SQL with concrete literal values when appropriate.
2. Or regenerate with a complete parameter list that matches placeholders exactly.
3. Retry execution only after the mismatch warning is cleared.

Symptoms: Chat shows a DATA policy or validation block for CREATE INDEX.
Cause: Genie does not allow CREATE INDEX in DATA mode because FileMaker manages indexing through field and storage settings.
Fix:
1. Remove the CREATE INDEX request from the DATA workflow.
2. Open the relevant table or field settings in FileMaker to manage indexing there.
3. Re-run the DATA request only for the remaining supported schema or data changes.