Sync Troubleshooting

This page covers the most common sync issues and how to resolve them.

Peers Not Discovered on LAN

If devices on the same network cannot find each other:

• Check your subnet — Both devices must be on the same local subnet. Guest Wi-Fi networks often isolate clients.
• Firewall rules — Allow UDP port 5353 (mDNS) and TCP port 9472 (localWiki sync) through your OS firewall.
• VPN interference — Some VPN clients route all traffic through a tunnel, blocking local mDNS. Try disabling the VPN or adding a split-tunnel rule for local addresses.
• Sync secret mismatch — Open Settings > Sync and confirm the sync secret shows “configured” in green. Both devices must share the same 12-word sync phrase.
• Restart the app — Closing and reopening localWiki forces a fresh mDNS broadcast on the local network.

Relay Connection Failed

If the WAN relay is unreachable:

• Check your plan — WAN relay requires a paid plan. Verify your subscription status in Settings > Subscription.
• Network restrictions — Corporate firewalls may block outbound connections to the relay. Check Settings > Sync for the relay address and ensure the required port is allowed.
• Relay status — If the relay is unreachable, your app continues working locally and over LAN. WAN sync will resume automatically when the relay is available again.

Conflict Resolution

localWiki uses Yjs CRDTs, so most concurrent edits merge without conflicts. In rare cases where two users restructure the same section simultaneously, both versions are preserved and the app shows an inline diff banner so you can choose the final version.

Checking Connection Status

Open Settings > Sync to view the connection panel. It shows:

The connected peers section lists each peer by name with a green “connected” indicator. If the list is empty and you expect peers, double-check that both devices share the same sync secret.