Peer-to-Peer Synchronisation Tips

For the first device, Setup URI, additional device, and two-way verification procedure, see Set up peer-to-peer synchronisation. For the communication and privacy model, see How peer-to-peer synchronisation works.

Important

P2P is a supported opt-in feature, but WebRTC connectivity still depends on the networks available to every device. A direct connection cannot be guaranteed in every environment.

A peer does not appear

Check discovery before changing any Vault settings:

Confirm that both devices use the same Signalling relay URLs, Group ID, and P2P passphrase.
Confirm that each device has a distinct device name.
Open P2P Status on both devices and confirm that each shows Connected.
Select Refresh after the other device joins.
If the peer remains absent, select Disconnect, then Open connection on the device which should be advertised again.

The signalling relay discovers peers; it does not prove that the networks can carry a WebRTC data connection.

A peer appears but synchronisation cannot connect

WebRTC may fail when UDP hole punching is blocked by carrier-grade NAT, a firewall, a VPN policy, or an intermediary gateway.

Try these in order:

Put both devices on the same ordinary network and retry.
Remove a VPN temporarily if it blocks peer traffic, or use a trusted VPN such as Tailscale when it provides a reachable path between the devices.
In P2P Configuration -> Advanced Settings, configure a trusted TURN service.
Under Connection compatibility, select TURN relay only to test the configured TURN path without direct ICE candidates.

TURN is a fallback for encrypted WebRTC traffic. It is different from the required signalling relay. The project does not operate an official TURN service. A TURN provider cannot read encrypted Vault contents, but it can observe connection metadata and traffic volume.

For a small self-hosted deployment, the repository includes an optional Coturn Compose starter. It uses static credentials and does not include TLS or a managed credential service; review its network and security boundaries before exposing it.

A connection opens but a transfer stalls

If peers can connect but a transfer repeatedly stalls on one network path, try the P2P message size presets under Connection compatibility. Start with Reduced, then try Conservative and Maximum compatibility only if needed.

The preset limits outgoing messages, so select the same value on every device which may send across the affected path. Smaller values add overhead and do not prove that packet fragmentation was the cause. Return to Standard when the path works reliably without the compatibility setting.

Compatibility choices are saved with the P2P profile. You may keep separate standard and compatibility profiles with the same Group ID and credentials, then select the profile appropriate to the current network.

A connected peer does not receive later edits

An open signalling connection does not automatically move every change.

Use Replicate now to prove an explicit bidirectional round trip.
Enable Announce changes on the source device before it dispatches notifications.
Enable Follow changes for that source on the receiving device before it fetches in response.
Use the peer's More actions menu only after the manual round trip works.

If the device was asleep, Obsidian was in the background, or the peer disconnected, run an explicit synchronisation after both devices are visible and connected.

Mobile limitations

Keep Obsidian visible and the device awake during initial transfer, rebuild, or a large synchronisation. Wake Lock support is best effort and cannot prevent the operating system from suspending or terminating a background application.

Collect evidence

If the same room works on one network but not another, include both network types in the report. Run Generate full report for opening the issue with debug info, remove credentials and private relay details, and state whether:

both devices reached Connected;
each device appeared in Detected Peers;
a connection request appeared; and
a TURN server or VPN was in use.

4.3 KiB Raw Blame History