obsidian-livesync/docs/tips/p2p-diagnostics.md

Diagnose P2P synchronisation

Use P2P Status to distinguish peer discovery, authentication, and data transfer before changing connection or database settings.

Participating devices must use compatible P2P transport versions. If your version does not show Diagnostic summary, use Peer-to-Peer Synchronisation Tips and include the installed versions in your report.

Capture one attempt

1. Keep both devices online, with Obsidian visible and the devices awake. Record which device originates the change and which should receive it.
2. Open P2P Status on both devices, using Self-hosted LiveSync: P2P Sync : Open P2P Status in the command palette.
3. In the P2P Status pane, expand Diagnostic summary below Stats. It starts collapsed. Record all three rows and their observation times before changing connection or database settings.
4. Turn the Diag toggle on in the P2P Status card, then select Open log inside the expanded summary. In the opened Log Pane, ensure Pause is cleared before reproducing the problem. New diagnostic lines contain [P2P Diag]; Verbose Log is not required for these lines.
5. Select Replicate now for the intended peer to test a manual round trip. Check P2P Connection Request prompts on both devices. For a problem with later automatic changes, first establish that the manual operation works, then make a small, non-private test edit on the source. Observe the receiving device as well as the source.
6. Record the last relevant messages and progress on both devices, then collect a report before restarting or retrying.

The summary continues updating with Diag off. Diag controls new detailed output in the Log Pane; enabling it does not replay earlier hidden lines. Diagnostic messages also enter the existing recent report history while Diag is off. Opening the Log Pane displays messages already in its display buffer. Repeated unchanged non-failure observations may be omitted, so the log is not a record of every network message. Pause affects only the log display; replication and the summary continue updating.

Read the summary

Each row holds the latest recorded observation in one category on this device. A new event from another peer can replace that row. Evidence can remain after a peer leaves or a connection closes; use the peer identifier and timestamp rather than reading the rows as a current connection-health checklist. The summary is held in memory and does not preserve history across a restart.

Row	Examples	What it establishes
Relay	Room opening, Room opened, Room could not open, Room closed	The local room lifecycle. 'Room opened; relay replies not observed' records local room opening. Relay acceptance remains unobserved; use later peer and sync observations to investigate discovery and data transfer.
Peer	Peer advertised, Peer left, Authentication accepted, Authentication refused, Authentication timed out	Discovery or the observed authentication outcome for the identified peer. A timeout indicates that the request exceeded its time limit, rather than an explicit rejection.
Sync	Pull started, Pull completed, Watching peer changes, Announcing changes, Change notification received	The latest observed pull, watch, announcement, or notification activity. Note that notifications signal a peer to fetch changes, rather than carrying Vault data directly.

• Not observed indicates that no event has been recorded yet for that category, rather than confirming success, failure, or a zero count.
• Unavailable means the diagnostic capability is unavailable in the current implementation. Include the installed version in the report.
• Authentication failed; authentication response not observed and Automatic watch skipped; peer announcement state not observed identify an unavailable response, rather than claiming refusal or disabled announcements.
• Summary times are local observation times, while [P2P Diag] lines include an observed UTC timestamp. Consider any device-clock differences when comparing reports across devices. Timestamps record when this device observed an event; they are not an ongoing heartbeat or live health check.

Relay rejection details are not provided by this diagnostic summary. Some existing RTC diagnostics also lack peer or room attribution and are not assigned to individual peers in these rows. Stats describes connection activity, whereas transferred document totals appear in transfer progress. If the summary cannot fully identify a failure, preserve the log output and note any unobserved categories in your report.

Understand transfer progress

During synchronisation, transfer counters appear next to each peer in the P2P Status pane, in the editor status bar, and in the main status bar when P2P is the active synchronisation method.

Indicator	Meaning
↑ / ↓	Successfully sent or received database document revisions for the observed peer and direction, including both Metadata and Chunks. These are not counts of Vault files written. A new replication attempt starts new counts.
⏩↑ / ⏩↓	Changes-feed entries compared in that direction, including entries already held by the receiver. The count can advance while no revisions need transferring.
seq	A compatibility display of database sequence progress when document statistics are unavailable. Interpret it as a sequence value, not a document total or percentage.

Each directional comparison label disappears three seconds after its count last changes. A hidden label alone does not establish whether comparison or replication has finished. A zero transfer count can be normal when the receiver already has the data.

Pull completed confirms that a single database pull has finished. To verify bidirectional synchronisation and full reflection, ensure the reverse direction completes and check the updated notes on the receiving device. For missing files, follow the corresponding troubleshooting procedure.

Choose the next check

Symptom or observation	Next check
The peer does not appear	Capture the Relay and Peer rows, then verify both devices' compatible versions, relay set, Group ID, and passphrase using discovery checks. A Connected status indicates that the local room is open; relay replies remain unobserved. Use peer and sync observations and both devices' logs to investigate discovery and transfer.
Authentication is refused	Confirm the peer identity on both devices and check for pending approval prompts. The summary displays the observed outcome; please ensure the connection request is explicitly accepted on the receiving device.
Authentication times out, or a peer appears but cannot transfer	Keep both devices active and check for an unanswered P2P Connection Request before troubleshooting network connectivity. Compare logs between devices, then follow existing WebRTC and TURN checks to inspect the data path.
Manual replication works, but later edits do not arrive	Confirm Announce changes on the source and Follow changes for that source on the receiver. Compare Announcing changes, Watching peer changes, and notification events on both devices. Change notification ignored; peer is not watched identifies a missing follow on the receiver.
A pull remains the last observation	Compare its timestamp, ↑/↓ and ⏩ changes, and both devices' logs. A subsequent operation may have replaced the summary row; verify with the surrounding logs and transfer counters to confirm whether a transfer is truly stalled. For a repeatable network-specific stall, use message-size checks.

After capturing the initial symptom, selecting Disconnect followed by Open connection and Replicate now can test reconnection. Because disconnecting cancels active operations, record whether a cancellation occurred. Testing reconnection, adjusting the message-size preset, or trying an alternative network can help isolate environmental differences.

Collect a report

Collect evidence from both the source and receiving devices around the same attempt. Include:

• the plug-in or client version on each device, and which device originated the change;
• the Diagnostic summary rows and times, plus the surrounding [P2P Diag] lines and any other relevant errors;
• whether the peer appeared, whether manual Replicate now worked, and the observed ↑/↓, ⏩, or seq values;
• whether Announce changes and Follow changes were enabled, and whether either application was in the background or the device had been asleep; and
• the network types and whether TURN or a VPN was used, especially when the same devices work on one network but not another.

Run Generate full report for opening the issue with debug info before the recent history is overwritten. It includes up to 1,000 recent log lines, including verbose diagnostic messages even when Verbose Log is off. For a problem which crosses a restart, follow the existing persistent logging procedure.

Review the complete report using the issue-reporting redaction guidance. New [P2P Diag] messages use fixed descriptions and shortened peer identifiers, but other log messages can still contain private information. Keep consistent device aliases across the reports when replacing private identifiers.