Skip to content
FUTO Notes

FUTO Notes sync troubleshooting: error messages and fixes

This page lists every message self-hosted sync can show, what causes it, and what to do. For problems on the server side, such as a container that won’t start, see Server errors.

Where sync messages appear

  • Desktop: a warning triangle replaces the sync icon, and the message also appears briefly as a notification. Hover over the triangle to read the message and click it to dismiss it. Settings → Sync shows the current status under the buttons.
  • iOS and Android: Settings → Self-hosted sync → Status. On iOS, the cloud icon above the note list opens the same screen.

Sync retries on its own after most errors, so a message can clear without you doing anything. To check straight away, press Sync now.

”Enter a server URL.”

The Server URL field is empty. Enter your server’s address, such as http://192.168.1.20:3005 or https://notes.example.com.

”Add http:// or https:// to the start of the server URL.”

The address has no scheme. Use http:// for a server on your own network without TLS, and https:// for a server behind a TLS reverse proxy.

”Couldn’t connect or sync. Check the server URL and password.”

The app couldn’t reach the server, or the server refused the password. Check these in order:

  1. Is the server up? From the device’s network, open http://<your-server>:3005/health in a browser, or run:

    curl http://<your-server>:3005/health

  2. Is the address right? Check the port (3005 unless you changed it at install) and whether you need https:// rather than http://. A server behind a reverse proxy is usually reached at https:// with no port.

  3. Is the password right? It is the sync password you chose when you installed the server, the same one on every device.

  4. Too many attempts? The server accepts 10 sign-in attempts per minute from one address. Behind a reverse proxy, all your devices share the proxy’s address. Wait a minute and try again.

”Sync failed. Try again.”

A sync stopped partway, usually because the server became unreachable or returned an error mid-sync. Press Sync now to try again. If it keeps failing, check the server’s logs from its install directory:

docker compose logs --tail 100

On desktop, you also see this if you used Forget password and then pressed Sync now. Enter the password in the Vault password field, then press Sync now again.

”The last sync failed. Try again.”

On iOS and Android, the app’s session with the server expired and it couldn’t sign back in by itself. Open Settings → Self-hosted sync, enter the password, and connect again.

”Sync completed with errors. Some changes could not reach the server.”

The sync finished, but some files didn’t make it. Sync retries them every time, so the message clears once the cause is fixed. Despite the wording, the cause can be on either end:

  • The server rejected uploads. A full disk or a permissions problem on the server’s data directory are the usual causes. Check the server logs as above.
  • A reverse proxy returned an error, such as a 502, while the server was restarting or unreachable.
  • The notes folder on this device isn’t writable, or its disk is full.
  • A note isn’t valid UTF-8 text. See What FUTO Notes syncs.
  • A note from another device has a name this device refuses: more than 10 folders deep, or a file or folder name longer than 255 bytes. Rename it on the device that has it. See name and folder rules.

”Live sync is temporarily unavailable. FUTO Notes will keep retrying.”

The app can’t keep its live connection to the server open. Sync still works, but more slowly:

  • Desktop keeps syncing every 15 seconds.
  • iOS and Android catch up each time the connection comes back, and whenever you tap Sync now.

Brief drops happen when the network changes or the server restarts, and they clear by themselves. If the message keeps coming back, the cause is usually a reverse proxy; see the next section.

Sync isn’t updating live behind a reverse proxy

Symptom: changes from another device take up to a minute to appear instead of about a second, or “Live sync is temporarily unavailable. FUTO Notes will keep retrying.” keeps coming back. It works on your local network and breaks through the proxy.

Cause: live sync is a long-lived stream at /api/sync/events. The server sends a keep-alive on it every 25 seconds, and the app reconnects if it hears nothing for 90 seconds. A proxy that buffers the response, or closes connections it thinks are idle, breaks the stream. The server sends X-Accel-Buffering: no so nginx doesn’t buffer it, but other proxies, tunnels and CDNs may.

Fix: turn off response buffering for /api/sync/events, and allow a read timeout well above 25 seconds. Reverse proxy setup has working configs for nginx, Caddy and Traefik.

Large notes or images never arrive

If small notes sync but a large image or note never shows up on your other devices, a limit on request size is the likely cause. The server accepts files up to 100 MiB, which is about 75 MiB for an image. A reverse proxy often has a much lower limit: nginx’s default is 1 MB. Raise the proxy’s limit to at least 100 MiB (client_max_body_size 100m; in nginx); see Reverse proxy setup.

After the fix, a file that was turned away uploads the next time it changes. To send a note straight away, make a small edit to it. For an image, update its modified time, for example with touch on desktop.

”Can’t find your vault folder at … Please reconfigure in settings.”

The desktop app shows this at launch when the notes folder is missing, for example on an unmounted drive, or after the folder was moved or renamed. Sync stops and doesn’t create an empty folder in its place. Reconnect the drive, or choose the folder again in Settings → Storage.

”Couldn’t remove the saved sync password.”

On desktop, Forget password or Reset connection couldn’t delete the password from the operating system’s keyring. The app tries again at the next launch. See Sync password.

The desktop app asks for the password after every restart

The app stores the sync password in the operating system’s keyring. If none is available, such as on a Linux desktop without a Secret Service provider like GNOME Keyring or KWallet, the password lasts only until the app quits, and the Vault password field shows “Required after restart”. Install and unlock a keyring, then enter the password once more. See Sync password.

Next steps