Troubleshooting

A diagnostic tree for the real failure modes users hit on install and first instance start. Start here before filing an issue.

Use this page when something that should work isn't working. Each section names a concrete symptom, explains what's happening, and gives the exact recovery command.

For a healthy-machine audit, prefer spl doctor — it runs seven checks and pinpoints which layer is failing.

"Failed to start spl serve" after install

$ spl serve
Error: failed to start spl serve

Read the full error:

spl serve --logs
# or directly
tail -n 50 ~/.syncro/logs/spl.log

The most common causes and their fixes:

`unable to open database file`

The instance could not open hub.db — either the path is wrong, the directory isn't writable, or the current working directory is in a location SQLite doesn't handle well (notably UNC or WSL-mounted paths on Windows).

Quick workaround: specify the store path explicitly.

spl serve --store ~/.syncro/hub.db

If that succeeds, the path resolution was the issue. On Linux and macOS the instance always uses ~/.syncro/hub.db implicitly; the --store flag just makes it explicit. On Windows, run from a native PowerShell (not a WSL shell) to avoid 9P filesystem weirdness.

`auth.required is enabled but no service accounts exist`

On Linux/macOS this is not an error — the local CLI authenticates over the Unix socket (filesystem-trust) and a zero-service-account instance is the canonical happy path. If you see this message anyway:

On Windows: Unix-socket trust is not yet wired for the Windows local-CLI path. Mint a bearer with spl pair --device local-windows --url http://127.0.0.1:9100 --scopes admin and save the printed token.
You've opted out of Unix-socket trust ([auth] unix_socket = false in config.toml): you've explicitly chosen the bearer-only model — see Service accounts for the pair flow.
You're on an older instance: upgrade with curl get.syncropic.com/spl | sh to land the canonical first-run flow.

The legacy "bootstrap dance" (--insecure-localhost → spl service-account create --bootstrap → spl token save) still works but is no longer required on the canonical first run.

`address already in use`

Another process is already on port 9100. Either a zombie instance, another spl serve, or a different program.

# Linux / macOS
ss -tlnp | grep 9100          # find the process
lsof -iTCP:9100 -sTCP:LISTEN  # alternative

# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 9100

If the owner is a stale spl, see "stale PID file" below. If it's a different program, either stop that program or start the instance on a different port with --port.

"Database is locked"

SQLite reports the store is locked. Two common causes.

A zombie `spl.exe` still holds the file (Windows)

Get-Process spl

If a process is listed with an old PID, kill it:

Stop-Process -Id <pid> -Force

Then start the instance again.

9P or WSL cwd interaction (Windows)

Running spl.exe from a WSL shell inherits a working directory under \\wsl$\<distro>\.... The Windows SQLite build does not play well with 9P filesystem locking. Symptoms: intermittent database is locked that clears after a machine reboot and returns the next time you start from WSL.

Fix: run spl from a native Windows terminal (PowerShell or Windows Terminal), not from a WSL shell.

Linux equivalent

Rare but possible. Check for orphan processes:

pgrep -af "spl serve"

If a PID is listed but spl stop can't find it, see stale PID file.

Dashboard shows "connected" but no records

The browser paired successfully (it can reach /health), but every /v1/records request is returning 401 or 403.

Cause: the browser has no token, or its token lacks records:read.

Fix: re-pair with appropriate scopes.

spl pair \
  --device "My browser" \
  --url "http://127.0.0.1:9100" \
  --scopes records:read,records:write

If the issue persists, verify the dashboard is on the CORS allowlist:

spl config show | grep -i cors
spl config auth-set-cors-origins https://syncropel.com

Windows: command hangs on first install

The install script runs spl.exe briefly to verify the version. Windows Defender and Windows Firewall both prompt on first run of a new executable. If the prompt lands behind other windows, the install appears to hang.

Check for a hidden prompt:

wf.msc

Accept the firewall prompt (or add an inbound rule manually for spl.exe in wf.msc). The install proceeds once the binary is allowed to bind.

`where.exe spl` returns nothing after install

where.exe spl
# (empty)

Your current PowerShell session predates the PATH registry update. The install script appended to user PATH, but that change only affects new sessions.

Fix: close the terminal and open a new one. where.exe spl should then report %LOCALAPPDATA%\Programs\spl\spl.exe.

If the new session still can't find it, verify the registry update landed:

[Environment]::GetEnvironmentVariable('Path','User')

The output should include %LOCALAPPDATA%\Programs\spl (or the expanded path).

Stale PID file

spl stop reports the instance isn't running, but spl status or curl http://127.0.0.1:9100/health shows an instance is clearly alive. The PID file has been orphaned.

Recovery:

# Linux / macOS
pgrep -af "spl serve"             # find the actual PID
kill <pid>                        # graceful
# if it doesn't exit within ~10 seconds:
kill -9 <pid>                     # force
rm ~/.syncro/run/spl.pid          # clear the stale file
spl serve                # start fresh

# Windows
Get-Process spl
Stop-Process -Id <pid> -Force
Remove-Item $env:USERPROFILE\.syncro\run\spl.pid -ErrorAction SilentlyContinue
spl serve

spl doctor detects stale PID files and prints the exact recovery command.

Corrupted hub.db or stuck locks

If hub.db is corrupted beyond a simple lock issue — perhaps after a disk-full event or a mid-write kernel panic — the nuclear option is to wipe ~/.syncro/ and re-initialize:

# First, make a backup if the file is at all recoverable:
cp ~/.syncro/hub.db ~/hub.db.broken.$(date +%s)

# Then wipe:
rm -rf ~/.syncro

# Re-initialize and re-bootstrap:
spl init
spl serve --insecure-localhost
spl service-account create --bootstrap \
  --name admin \
  --actors did:sync:user:$(whoami) \
  --scopes admin \
  --with-token
spl token save spl_prod_sa_...
spl stop
spl serve

Any records you had are gone. Automatic backups at ~/.local/share/syncropel/backups/hub.db.bak may contain a recent snapshot — see Operator runbook → Recovery for the full restore procedure.

Data went to `System32` (Windows)

If you ran spl serve from an elevated cmd.exe whose working directory was C:\Windows\System32\, and the instance's path resolution was misbehaving, hub.db may have been created in System32. Symptoms: no data in %USERPROFILE%\.syncro\, but the instance reports records exist.

Fix: stop the instance, move the file, point the instance at the right location.

spl stop
Get-ChildItem C:\Windows\System32\hub.db -ErrorAction SilentlyContinue
# If found:
Move-Item C:\Windows\System32\hub.db $env:USERPROFILE\.syncro\hub.db
spl serve --store $env:USERPROFILE\.syncro\hub.db

Always start spl serve from a working directory you control (your home directory is safe). Never run as Administrator unless you have a specific reason — the user-scope install does not need it.

Still stuck

Run the full diagnostic:

spl doctor --json

Every check reports pass, warn, or fail with a specific fix. If doctor is green but behavior is still wrong, capture the instance log around the failure — spl doctor --json produces a machine-readable summary you can attach when reporting the issue.