debugging

When the user wants to debug a production error, diagnose it using the Faultline MCP tools — don't ask them to paste a stack trace from the dashboard.

Investigation order

Follow these steps; skip any that don't apply.

1. Find the error group. If the user named an error class or message, call list_error_groups with search: and pick the most plausible match. If they gave a numeric id, skip to step 2.
2. Get group context. Call get_error_group with the id. The response includes a summary of the 10 most recent occurrences (no backtraces or locals — those are intentionally omitted to keep the response small).
3. Pull a full occurrence. Call get_occurrence with the most recent occurrence id to get the full backtrace, captured local variables, filtered request params, request headers, and source context. This is the step that actually lets you fix the bug — don't propose a fix without seeing the locals.
4. Optional: trace performance. If the error looks performance-related (timeouts, ConnectionTimeoutError, slow queries), call list_traces with the relevant endpoint, then get_trace for span detail.
5. Propose a fix. Cite specific files and line numbers from the backtrace. Use the local variables to ground claims about what data flowed in.

Tools available

Read-only:

• list_error_groups — recent groups, filter by status/since/search
• get_error_group — single group + recent occurrence summary
• get_occurrence — full occurrence with backtrace, locals, request data
• recent_occurrences — paginate occurrences for a group
• error_stats — time-bucketed counts
• list_traces / get_trace — APM data (only when enable_apm is set on the host app)

Mutating (only available when the Faultline app sets mcp_readonly: false):

• resolve_error_group — mark resolved
• ignore_error_group — mark ignored
• create_github_issue — open a GitHub issue with full context

Common pitfalls

• Don't fetch the occurrence first. Fetching the group first gives you the right id and lets you rule out resolved or ignored groups before deep-diving.
• Don't ignore captured locals. They are the highest-signal data Faultline provides over a raw stack trace — the actual variable values at the moment the exception fired.
• Mutating tools may return error: "Tool disabled: mcp_readonly is true". That's expected on production-default installs. If the user wants you to resolve/ignore/file issues directly, tell them to set c.mcp_readonly = false in their Faultline initializer.
• Filtered params are filtered. Faultline applies Rails.application.config.filter_parameters plus config.sanitize_fields. If you see [FILTERED] in request_params, that's by design — don't ask the user for the underlying value.