MCP troubleshooting

Begin with lomi_status and lomi_diagnostics. Status can report connection phase, pairing request ID, UI readiness, platform and capabilities. A listed capability can be unavailable, unauthorized or unqualified; catalog presence alone is not usable access.

Connection checklist

1. Confirm macOS 14+ and Apple Silicon. The current desktop host check blocks other platforms.
2. Open Lomi and start Settings > Agent control > Start server. Check startup/storage errors there.
3. Ensure the client can run the registered absolute executable. If Lomi moved, register it again.
4. Restart/reload the client’s MCP connection after registration or a Lomi/server restart.
5. With YOLO off, match pairingRequestId in Sessions, approve the intended workspace/scopes, then call lomi_workspace_list and lomi_connect.
6. Confirm uiReady before UI-dependent work. Re-registering the workbench can require a new connection.

app_unavailable usually requires an open server or a valid registration. connecting is in progress; pairing_required awaits Settings. disconnected needs a new connection. host_unqualified is not solved by adding permissions. Built-in Chat with unavailable access should report the Settings next step and retry in a later turn, rather than busy-poll or execute outside the broker.

The CLI is missing or setup is refused

The picker shows installed executables from the supported local shell environment. Install the CLI in that environment and refresh; an old config file is insufficient. A running process with a custom home can use a different configuration from Settings. See client profiles.

If another server is named lomi, rename that conflicting entry using your client’s configuration workflow, then retry setup. Lomi preserves the file. A revision conflict means the configuration changed after inspection: refresh first. For invalid JSON/TOML/YAML or ambiguous/additional config sources, repair or choose the source in the client; Lomi does not guess or replace malformed data.

If tools appear but a modifying call never reaches Lomi, check client-side approval. If it reaches Lomi and returns SCOPE_DENIED, review the Lomi session grant. These are independent policies.

Error codes

Code	What to inspect or do next
APP_UNAVAILABLE	Open Lomi, start its server and verify the executable/discovery registration.
PAIRING_REQUIRED	Match and approve the pending request in Sessions.
SCOPE_DENIED	Review the required permissions and exact workspace/device/origin/conversation grant.
UI_NOT_READY	Wait for a live workbench registration; inspect modal or startup state.
APP_CLOSING	Finish or cancel the application’s close/update flow before new work.
TARGET_NOT_FOUND	Refresh the authorized list; the target may be closed, moved or outside the grant.
STALE_GENERATION	Read the current runtime identity. Never apply an old lease to its replacement.
REVISION_CONFLICT	Inspect prior effects, then read the relevant fresh layout/disk/buffer/settings/Chat revision.
STALE_SNAPSHOT	Take a new browser/Android observation and use its current references.
TARGET_BUSY	Inspect the active operation, human ownership, dirty/conflicted buffer or resource readiness.
CONTROL_REVOKED	Restore an explicitly approved connection/control if still intended.
PROMPT_STATE_UNKNOWN	Inspect the terminal; an idle prompt was not safely established for automatic run.
PANEL_NOT_RENDERABLE	Reveal the exact browser panel and remove occlusion; hidden capture/input may be unsupported.
PROTECTED_ORIGIN_TERMINAL	Use another authorized terminal; the agent’s origin is protected.
UNSUPPORTED_CAPABILITY	Use a documented supported path; scope approval cannot add an implementation.
HOST_UNQUALIFIED	Consult the host qualification; another successful feature does not qualify this path.
DEADLINE_EXCEEDED	Inspect the receipt and actual resource for effects before another request.
CURSOR_EXPIRED	Restart the read from a fresh observation; do not combine unrelated pages.
ARTIFACT_TOO_LARGE	Reduce the requested size or use a supported smaller source.
ARTIFACT_INVALID	Verify ownership, immutable hash, expiry, source classification and source access.
OUTCOME_UNKNOWN	Preserve the receipt and inspect the actual effect; do not automatically repeat.
IDEMPOTENCY_CONFLICT	The same key has different arguments. Recover the exact original request.
RETRY_WINDOW_EXPIRED	Old retry identity cannot dispatch; reconcile its effect before deliberate new work.
RESOURCE_EXHAUSTED	Check request/output bounds, producers/queues, artifacts and receipt/epoch budgets.
STORAGE_UNAVAILABLE	Preserve the store, inspect permissions/lock/disk capacity and stop new effect requests.

Some native conditional failures are returned as an operation result rather than a top-level error. Read state, effectState, typed result, omission counters and concrete failures together. outcome_unknown is also a receipt state.

A command, save or transfer timed out

Retrieve the original receipt using operationId or its exact retry key. Keep the original payload and revision. A duplicate is safe only under the tool’s exact deduplication contract; a new key can perform a second effect.

Inspect the actual destination: terminal completion/output, saved file revision, Git index/HEAD/remote state, page attachment, installed Android package or saved Chat request. Cancellation is not rollback. A truncated observation is not proof the target or effect is absent.

For APK INSTALL_FAILED_INSUFFICIENT_STORAGE, free space on the selected device and inspect the failed operation. Reusing its exact key returns that failure. Create a new install request only after the device’s actual state is understood.

Receipt storage recovery

Agent control stores control.sqlite3, its matching control.sqlite3-wal/control.sqlite3-shm, registration identity and other private control data below the application’s agent-control data directory. Do not edit a live SQLite/WAL store or delete it to make a retry work.

If startup rejects corrupt/truncated/oversized WAL, unsupported schema, ownership/permission problems or another owner, stop Lomi before offline recovery. Preserve the complete original directory and matched database/WAL/SHM set together. The current WAL startup validation budget is 128 MiB; rejected history is not silently dropped.

Restore only a deliberately selected offline backup, keeping damaged originals. Pair again and reconcile actual resources; an older backup cannot prove that an effect never dispatched. Old epochs cannot authorize replay. There is no automatic receipt pruning or documented online reset command: at 4,096 receipts/epochs, plan explicit offline maintenance that retains evidence of unfinished effects.

Trash recovery

For an interrupted Trash operation, use Settings > Agent control > Show recovery folder. Its private trash-recovery entries contain retained data and plan.json with the original destination. completed.json records completed publication to system Trash.

Inspect the entry and receipt together. Recover to an unused destination name to preserve newer work. Keep recovery records until the retained contents and actual Trash state are reconciled. A successful Git discard is different: it does not retain discarded worktree bytes in this recovery folder.

Verification limits

The current MCP qualification is host-specific. Browser synthetic input cannot satisfy every trusted-gesture workflow, Android UI projections can miss Canvas/WebView/secure content, Git linked worktrees are unsupported and plugin layout paths can be unqualified. These failures are not fixed by enabling YOLO.

See architecture and evidence for tests actually run during this documentation review and the separately retained native acceptance records.

Source: error enum, helper connection phases, store/WAL recovery, operational recovery guidance.