Troubleshoot MCP results

Frigg returns structured recovery in both successful empty responses and MCP transport errors. Read response error_code, zero_hit_reason, completeness, and next_actions; for transport errors, also read data.error_code and data.retryable.

Empty rows do not prove absence

Cause: The request can be complete, truncated, ranked, unavailable, scoped too tightly, stale, or intentionally count-only.

Fix:

1. Read completeness.unit, complete, total, truncated, and both reason arrays.
2. If count_only=true, read total_matches; empty matches[] is intentional.
3. Inspect zero_hit_reason, applied scope, and index freshness.
4. Invoke an appropriate canonical next_actions[] entry.

Common zero-hit reasons:

Reason	Recovery
indexed_search_complete	Treat zero as authoritative only for the reported scope and unit.
query_miss	Try a known identifier, exact phrase, or broader discovery query.
query_looks_like_regex	Retry search_text with pattern_type=regex if metacharacters are intentional.
scope_excluded_all_candidates	Remove or relax path_regex, glob, exclusions, or path class.
wrong_repository_possible	Call workspace, adopt the intended repository, and retry.
path_class_not_indexed	Choose a covered path class or inspect workspace/index readiness.
index_stale_possible	Follow workspace.freshness.post_edit.strategy.
index_not_ready / no_index_coverage	Run CLI frigg index when workspace guidance requires it.
precise_graph_unavailable	Use exact text, symbols, source reads, or structural search; generate/index precise data when needed.

STALE_CONTINUATION

Cause: Repository snapshot state changed after the continuation was issued.

Fix: Re-run the original tool without a continuation and page from its new token.

Retrying the stale token unchanged is not useful.

CONTINUATION_SCOPE_MISMATCH

Cause: The token belongs to another tool, normalized request, repository, or session.

Fix: Repeat the exact original request with the token, or start a new search without it. Do not edit or transfer opaque tokens.

MIXED_CONTINUATION_FORMS

Cause: The request contains both legacy resume_from and canonical continuation.

Fix: Remove resume_from and keep completeness.continuation.

STALE_HANDLE

Cause: The result handle expired, was evicted, or belongs to a different MCP session.

Fix:

1. Re-run the producer tool in the current session.
2. Use its new result_handle and row match_id.
3. If the old read_match request carried origin, prefer the exact retry in next_actions.

MIXED_HANDLE

Cause: The match_id was paired with a handle from another response.

Fix: Keep each row with the response-level handle that issued it. If that pairing is unavailable, re-run the producer.

STALE_PROOF_ANCHOR

Cause: The matched source changed, disappeared, or cannot be validated against the producer revision.

Fix: Re-run the producer against current source, then proof-read the new match. Do not replace the failed proof with current read_file bytes while presenting it as the old result.

Target identity errors

Error	Cause	Fix
CONFLICTING_TARGET_INPUT	target was combined with symbol/location fields.	Send the copied target alone.
TARGET_REPOSITORY_MISMATCH	Top-level repository assertion differs from the target.	Remove the assertion or select a target from that repository.
TARGET_SCOPE_MISMATCH	Result target belongs to another session/scope.	Re-run its producer in this session.
STALE_TARGET_SNAPSHOT	Stable-symbol snapshot is obsolete.	Re-resolve the symbol and use the new target.
TARGET_NOT_FOUND	Repository or symbol identity is absent.	Check workspace, then search again.
TARGET_ANCHOR_INSUFFICIENT	Exact location cannot be derived.	Resolve through search, outline, or a tighter direct source location.

Navigation returns no rows

Cause: The target can be ambiguous, precise coverage can be missing, or the result can be a valid complete zero.

Fix:

1. Read target_selection.status and candidate details.
2. Read navigation mode.
3. For calls, read availability before interpreting zero.
4. Read completeness independently from mode.
5. Follow exact next_actions for disambiguation, precise-data diagnosis, or alternate evidence.

unavailable_no_precise is not proof of absence. outgoing_calls is always provisional, even when rows are present.

resource_not_found for an MCP resource

Cause: The requested frigg:// URI is unknown to the running binary.

Fix: Refresh MCP resources/list and use an advertised URI from MCP resources, prompts, and playbooks.

Protocol versions can map the outer JSON-RPC error differently. Branch on data.error_code=resource_not_found.

A tool is missing

Cause: The client cached an older schema, the active profile filters the tool, or the binary lacks the required feature.

Fix:

1. Refresh MCP tools/list.
2. Read workspace.runtime.tools_exposed or frigg://policy/tool-surface.json.
3. Confirm FRIGG_MCP_TOOL_SURFACE_PROFILE.
4. For playbook_*, confirm the binary was compiled with --features playbook and the profile is extended.

explore and impact_bundle are core product tools. Their absence indicates a stale/older binary or client view, not the expected profile split.

Invalid read presentation

Cause: include_context_efficiency=true was requested without JSON, or presentation_mode=text was sent to explore probe/refine.

Fix: Use presentation_mode=json for efficiency metadata. Omit presentation mode for structured probe/refine responses.

Storage or semantic transport failures

Read data.retryable:

• storage_schema_incompatible is non-retryable without correction. Delete the regenerable database named in the error and run frigg index as instructed.
• strict semantic unavailable can be retryable after provider/runtime recovery.
• timeout failures can be retryable.
• invalid_params, resource_not_found, and access denial require request or environment correction.

For substrate-specific recovery, see troubleshoot freshness and storage and troubleshoot semantic and precise retrieval.

Source Anchors

• ../frigg/crates/cli/src/mcp/types/completeness.rs
• ../frigg/crates/cli/src/mcp/types/target.rs
• ../frigg/crates/cli/src/mcp/types/recovery.rs
• ../frigg/crates/cli/src/mcp/server/errors.rs
• ../frigg/crates/cli/src/mcp/server/presentation.rs
• ../frigg/crates/cli/src/mcp/server/next_actions.rs
• ../frigg/crates/cli/tests/rmcp_protocol.rs