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.

Local MCP Bridge: 400 / SSE fallback connection failure

• 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).

Local MCP Bridge: Claude Desktop cannot see Genie tools

• 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.

Local MCP Bridge: an agent keeps using XML staging for normal requests

• Symptoms: Cursor, Codex, Claude, or another MCP client sends fmxmlsnippet for plain English script requests.
• Cause: Script staging should default to Script Schema JSON through genie_scripts. Raw 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 script creation, call genie_scripts action:get_schema, fetch targeted step/catalog records, then use genie_scripts with result_type: "new_script".
  3. For edits, read exact live content with genie_scripts action=get_content (or use genie://context/scripts), then stage result_type: "delta_edit". merge_ready:false does not block staging; select/open the target before Apply.
  4. Use fmxmlsnippet only when the request includes complete Script or Step XML.

Local MCP Bridge: metadata preflight asks for API words

• 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 script request with genie_scripts.
  2. Use genie_metadata action:parse_selection only when the prompt references real FileMaker tables, fields, layouts, scripts, custom functions, value lists, or ExecuteSQL schema references.
  3. Keep genie_query for read-only SELECT work, not for Insert from URL script generation.

Local MCP Bridge: agent uses genie_query for schema discovery

• Symptoms: An MCP client tries to learn field lists or relationships by running SELECT queries.
• Cause: genie_query is only for actual read-only row data.
• Fix:
  1. Use genie_metadata action:get_tables, get_fields, get_layouts, or get_relationships for structure.
  2. Use genie_query only after the schema is known and the request needs row data.
  3. For DATA staging, pass a metadata_selection bundle from genie_metadata action:parse_selection.

AGENT: answer stops with a clarification

• Symptoms: AGENT asks one concrete question instead of producing code or a final answer.
• Cause: AGENT could not safely determine intent, target identity, required metadata, destructive scope, or applyability.
• Fix:
  1. Answer the specific question in chat.
  2. If the issue is script target identity, open the desired script in Script Workspace, capture it with Add Selection, or add it from Metadata Explorer.
  3. If metadata is missing, refresh or select the relevant items in Metadata Explorer.

Export Failures (CSV/PNG)

• 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.

DATA Migration: No active plan or stale action click

• 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.

DATA Migration: Step is halted after failure

• 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.

DATA Migration: Execute All not available

• 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.

DATA Migration: Full-table confirmation text mismatch

• 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.

DATA Migration: Placeholder mismatch block

• 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.

DATA Migration: CREATE INDEX is blocked

• 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.

Related pages

• Mode Behavior Matrix
• Settings Guide
• Troubleshooting Overview