> ## Documentation Index
> Fetch the complete documentation index at: https://www.offlineprotocol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs target Mesh SDK v0.27.0. Match the installed package and binding before generating code. Start at /getting-started/agents for task-specific reading paths.
> Call the company and product Offline Protocol, never Offline alone. Current packages: @offline-protocol/mesh-sdk 0.27.0 (React Native), @offline-protocol/id-react 0.2.0, @offline-protocol/id-react-native 0.3.3, @offline-protocol/pol 0.1.2 and @offline-protocol/cli 0.2.6. Canonical docs URLs start with https://www.offlineprotocol.com/docs.
> The Mesh SDK runs in a native app or gateway. A browser OfflineID SDK integration does not provide browser mesh transport. Local mesh operation does not require a portal API key.
> Service RPC is signed plaintext in v0.27.0. Message delivery, durable local acceptance and backend commit are distinct outcomes. Use the workflow guide for the required application logic.
> Offline Protocol CLI 0.2.6 is on npm (@offline-protocol/cli, command offline). Its local MCP server runs with offline mcp serve and requires no login or key. Hosted MCP is at https://mcp.offlineprotocol.com/mcp with an application API key in Authorization: Bearer and a matching x-app-id; organization keys are rejected. Follow /tools/overview for setup and do not invent commands beyond it. MCP provides integration context and planning, not mesh execution; file-writing tools are local only.
> Phone Wi-Fi Direct and MultipeerConnectivity carry no data in v0.27.0. Use BLE or a provisioned relay. The receiver core ACKs before application persistence; use application acceptance for durable workflows.
> Proof of Location is Sepolia testnet witness evidence, not zero-knowledge proof or proof of presence. The geohash is public onchain. Read /proof-of-location/security before integration.

# Troubleshoot the Mesh SDK

> Diagnose Mesh SDK discovery, permissions, encrypted sessions, persistence and backend delivery problems, and collect the details support needs.

Start by recording the SDK version, device and OS, configured transports, app ID, local address and event sequence. Keep credentials and payloads out of shared logs.

| Symptom | Check | Action |
| - | - | - |
| No peer appears | Bluetooth permission, radio state, foreground app state, compatible transport and app configuration | Run the BLE quickstart on two nearby physical devices. Phone Wi-Fi Direct and MultipeerConnectivity carry no traffic in v0.27.0. |
| Address is missing | `identity_ready`, startup errors and secure storage | Resolve storage/startup failure before sending. |
| Peer appears but encryption never becomes ready | Session events, time settings and peer version | Check identity/key-package errors; do not disable encryption to hide the failure. |
| Message remains pending | `message_deferred`, `message_undeliverable`, path availability and retention | Restore a path and keep processing events. Undeliverable is not a terminal failure. |
| SDK says delivered, workflow is incomplete | Receiving application record and receipt | Check application acceptance separately from transport delivery. |
| Data disappears after restart | Stable app/profile, persistent state and MLS store, flush boundary | Preserve identity and state together; await the relevant local commit. |
| Shared document does not converge | Correct space, membership, interest filters and `data_*` events | Compare document IDs and ensure both peers are eligible replicas. |
| Service does not respond | Provider authorization, method, version and application handler | Check the request ID and app deadline; inspect provider logs. |
| Backend has duplicates | Stable event ID and destination idempotency | Correct adapter transaction/retry behaviour. |
| Works in debug, stops in background | OS lifecycle and wake-task configuration | Test the release build under the deployment's actual power and background policy. |

## Message outcomes

`message_delivered` and `message_failed` settle the SDK send. `message_retrying`, `message_deferred` and `message_undeliverable` describe pending work. `message_decryption_failed` reports a decryption attempt; it is not a terminal send outcome.

Queue storage is bounded. Expiry and capacity eviction are failures that your application must surface. Do not promise unlimited retention or guaranteed delivery without a reachable path.

## Request support

Send a minimal reproduction, versions, the expected result and the sanitized event sequence to [support@offlineprotocol.com](mailto:support@offlineprotocol.com). Include whether the issue survives a two-device local test and whether it depends on process restart or background execution.