# Troubleshooting

> The problems that actually come up: a server behind the app, a missing folder, notes that will not sync, and uploads that fail in the client.

Source: https://baalda.com/docs/troubleshooting
Site: Baalda, https://baalda.com

## A notice says the backend is behind

The desktop app updates itself and your server does not. Redeploy the server from the latest release, or pull and rebuild the image. Migrations run before the server starts. The notice clears on the app's next check, within ten minutes, or at once after a restart. Check what the server reports with `curl https://<your-server>/health`.

## The vault's folder is missing

The banner offers Restore here, which recreates the folder at the same path and syncs everything down, and Locate folder, for when it was moved. A local-only vault only gets Locate folder, because nothing can be synced down. While the folder is missing, tabs close and the sync pill reads Paused.

## Notes stay unsynced

- Check the sync indicator first: it describes the vault's connection, so a stuck state is usually the connection rather than the note.
- Files that were wrongly removed from the server while they were still on your computer re-register and upload again on their own.
- On a plan without standalone file sync, files that are not embedded in a note stay on this computer by design, and the app says so rather than retrying.
- As a last resort on one device, Reset local copy deletes that device's folder and restores it from the Remote Vault, after naming anything unsent.

## Search results look stale

The local index can trail the files after a bulk change made while the app was closed. It is derived data, so rebuilding it is safe: it re-reads the Markdown and reconstructs search, backlinks and tags.

## Someone cannot see a note you shared

1. Check the item's own level, then the Everyone row, then that person's vault-wide level. A No access anywhere in their own chain beats a grant above it.
2. Remember that New members is a snapshot taken when they joined: changing it later does not reach back to people already in the vault.
3. A lock caps at view and never grants, so a locked item under a sealed vault is still No access.

## Uploads fail in the client while the server looks healthy

That is the signature of a missing bucket CORS policy on an S3-backed server. The server never sees the request, so its logs are clean. Apply the policy from the deployment document.

## The app will not connect to a LAN server

Packaged builds can only reach plain `http://` on localhost or 127.0.0.1. A server at `http://192.168.x.x:3010` needs TLS or an SSH tunnel.

## An MCP client gets 401

The token was revoked, belongs to another vault, or was never sent. Tokens are shown once at creation: if it was lost, revoke it in Vault Settings, MCP and create another. The 401 also carries a header that points an OAuth-capable client at the authorization server.
