Embedded database & local data
Fix startup problems of a Synq that runs on its built-in database (the database lock, "can't reach the server", a corrupted data folder), and find where that data lives, including the data an older desktop app kept on your computer.
This page is for people who run Synq with its built-in database: a bare self-hosted install (no Docker). The standard server install (Docker Compose with Postgres, set up by the installer) keeps its data in Postgres, so most of this page doesn't apply to it.
The desktop app keeps no Synq data
The desktop app only shows your Synq panel, so none of this applies to it. Versions up to 1.2.5 could run a separate Synq on your computer; its data is still there after an update. See where the desktop app's data is to keep or delete it.
One folder, one process
When you don't point Synq at a real Postgres, it uses PGlite, an embedded Postgres that keeps everything in a single folder on disk. Only one Synq process may use that folder at a time. Most of the problems below come from two processes trying to share it, or from that folder getting into a bad state. If you run your own Postgres (the Docker Compose setup), the lock issues here don't apply to you.
"Another Synq instance is already using the database"
Symptom / what you see
Synq won't start. The process exits on launch and your terminal (or log) shows a message like:
Another Synq instance is already using the database at
/…/data(pid 12345). PGlite allows only one process per data directory; opening a second would corrupt it. Stop the other instance (e.g. quit the desktop app) and retry. If you are certain no Synq process is running, remove:/…/data.lock
What it means (plain words): the database folder can only be opened by one program at once, and
something is already holding it. Usually that "something" is another copy of Synq: a bun dev you left
running, a second synq process, or an older process that didn't shut down yet.
How to fix:
Close the other one
Stop any other Synq you have running (a terminal running synq or bun dev, or a leftover process from an
update), then start Synq again.
Give it a moment, then retry
If Synq crashed last time (rather than quitting cleanly), the lock heals itself on the next start once it sees the old process is gone. It also waits a few seconds for a clean hand-off during restarts. Wait a moment and launch again.
Only if you're certain nothing is running: remove the lock
The message ends with the exact path of a lock file, named <data-dir>.lock (a sibling of your data
folder). If you're sure no Synq process is alive, delete that one file and start again. It's safe to
remove: it never contains your data. Do not delete anything inside the data folder itself.
“…locked by a process on a different host”
A different wording, "The Synq database … is locked by a process on a different host … PGlite data
directories cannot be shared across machines", means your data folder is on a network/shared drive that
another machine opened. PGlite folders can't be shared across computers. Move the data to local disk (or set
PGLITE_DATA_DIR to a local path), and remove the lock file it names only
if that other host is truly done with it.
"Cannot reach the server" on start
Symptom / what you see
The dashboard opens but stays blank or shows a red toast reading “Cannot reach the server. Make sure the
API is running.” In logs you may see the raw Node message fetch failed.
What it means (plain words): the dashboard is up but the API isn't answering yet. Most often it's simply still booting; occasionally the API crashed on startup, and the most common reason it crashes is the database lock from the section above.
How to fix:
- Wait a few seconds. On the first start after an install or update the API has to run database migrations before it answers. Give it up to a minute.
- Check it isn't really the lock error. If the API's log also says "already using the database," fix that first: a locked-out API never comes up, which is what leaves the dashboard unable to reach it.
- Restart the API and read its log from the start: it says why it stopped.
Where your local data lives
Everything Synq stores locally sits in one place per install. Stop Synq before touching any of it.
| Install | Data folder |
|---|---|
| Self-hosted / CLI (default) | ~/.synq/data |
| Self-hosted with an override | whatever you set in PGLITE_DATA_DIR |
| Local Synq of a desktop app up to 1.2.5, Mac | ~/Library/Application Support/Synq/data |
| Local Synq of a desktop app up to 1.2.5, Windows | %APPDATA%\Synq\data |
Beside the data folder sits <data-dir>.lock, the single-instance lock (a sibling of the data folder,
never inside it). Safe to delete only when no Synq is running.
Set your own data path (self-hosted)
Point the self-hosted API at any folder with the PGLITE_DATA_DIR environment variable, recommended if the
default ~/.synq/data isn't where you want your data to live. A leading ~ is expanded for you.
Recovering a corrupted database
Symptom / what you see
Synq won't start and the logs show RuntimeError: Aborted(), often alongside
DrizzleQueryError: Failed query: CREATE SCHEMA IF NOT EXISTS "drizzle".
What it means: the embedded database folder was damaged, most often by a hard kill mid-write, or by two processes opening it at once (exactly what the lock exists to prevent). It's a data-folder problem, not a bug in your project.
How to fix: run the repair, which backs up your data before changing anything:
synq doctor # interactive: backup, heal, verify
synq doctor --fix # the same light repair with no promptsIt copies your data aside first (to <data-dir>.backup-…), clears a stale lock and trims the corrupt tail, so you
can always fall back to the original if recovery isn't what you wanted.
Last resort
If it won't recover, stop Synq, copy your data folder somewhere safe, then move the original aside. Synq creates a fresh, empty database on the next start. This gets you running again but starts you over: your backed-up copy is your only route back to the old data, so keep it.
Still stuck?
Host control channel
"This operation targets the HOST machine, but no host channel is configured" — what the host channel is, why the rest of the install looks healthy, and the repair for each install shape.
Common errors
The API error codes and messages you'll actually hit — what each one means, and how to fix it.