# Embedded database & local data
URL: https://synquic.tech/docs/troubleshooting/desktop-data.md

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.

import { Step, Steps } from 'fumadocs-ui/components/steps';

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.

<Callout title="The desktop app keeps no Synq data" type="info">
The [desktop app](/docs/getting-started/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](/docs/getting-started/desktop-app#where-your-data-is) to keep or delete it.
</Callout>

<Callout title="One folder, one process" type="info">
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.
</Callout>

## "Another Synq instance is already using the database"

<Callout title="Symptom / what you see" type="error">
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`
</Callout>

**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:**

<Steps>

<Step>
### 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.
</Step>

<Step>
### 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.
</Step>

<Step>
### 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.
</Step>

</Steps>

<Callout title="“…locked by a process on a different host”" type="warn">
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`](#where-your-local-data-lives) to a local path), and remove the lock file it names only
if that other host is truly done with it.
</Callout>

## "Cannot reach the server" on start

<Callout title="Symptom / what you see" type="error">
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`.
</Callout>

**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:**

1. **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.
2. **Check it isn't really the lock error.** If the API's log also says "already using the database," fix
   [that](#another-synq-instance-is-already-using-the-database) first: a locked-out API never comes up,
   which is what leaves the dashboard unable to reach it.
3. **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.

<Callout title="Set your own data path (self-hosted)" type="info">
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.
</Callout>

### Recovering a corrupted database

<Callout title="Symptom / what you see" type="error">
Synq won't start and the logs show `RuntimeError: Aborted()`, often alongside
`DrizzleQueryError: Failed query: CREATE SCHEMA IF NOT EXISTS "drizzle"`.
</Callout>

**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**:

```bash
synq doctor          # interactive: backup, heal, verify
synq doctor --fix    # the same light repair with no prompts
```

It 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.

<Callout title="Last resort" type="warn">
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.
</Callout>

## Still stuck?

<Cards>
  <Card title="Installation" href="/docs/getting-started/installation" description="Install Synq on a server with one command and your license key." />
  <Card title="Updating" href="/docs/guides/updating" description="Upgrade to a newer release by running the installer again." />
  <Card title="Self-host infrastructure" href="/docs/cli/self-host" description="Run Synq as a background service on your own box." />
  <Card title="Deployment problems" href="/docs/troubleshooting/deployments" description="Builds that fail, apps that won't come online." />
</Cards>