Troubleshooting¶

Common issues when deploying and integrating Privitty Edge.

Container won't start¶

Symptom: Container exits immediately or shows Restarting (1).

Check:

docker logs privitty-edged

Common causes:

Cause	Fix
Missing `PRIVITTY_PROFILE`	Set `-e PRIVITTY_PROFILE=gateway01`
Port already in use	Change host binding: `-p 127.0.0.1:7201:7200`
Volume not writable	See Volume permissions on Docker Desktop below

Volume permissions on Docker Desktop¶

Symptom:

Fatal: Failed to secure accounts directory: Operation not permitted (os error 1)

or:

Fatal: Failed to secure accounts directory: Accounts directory /var/lib/privitty is not writable: Permission denied (os error 13)

Cause: Docker Desktop on macOS/Windows often creates named volumes owned by root. The daemon runs as UID 1000 after startup and needs write access to /var/lib/privitty.

Fix (current images): The entrypoint starts as root, chowns the volume to UID 1000, then drops privileges. Pull a recent privitty/edge:latest and re-run your docker run — no manual init required.

Fix (older images or --user 1000): Init volume ownership manually:

docker rm -f privitty-edged
docker volume rm privitty-data

docker volume create privitty-data
docker run --rm -v privitty-data:/var/lib/privitty alpine:3.19 \
  sh -c "chown 1000:1000 /var/lib/privitty && chmod 700 /var/lib/privitty"

# Re-run your docker run command (do not pass --user unless you know why)

If the directory is still not writable, logs will say Accounts directory /var/lib/privitty is not writable.

Health check failing¶

Symptom: Docker shows (unhealthy) or curl /health times out.

Causes:

Still provisioning — first boot takes 10–60 seconds. Wait and retry.
Daemon crashed — check docker logs privitty-edged.
Wrong port binding — ensure host port maps to container 7200.

curl -v http://127.0.0.1:7200/health
docker exec privitty-edged /usr/local/bin/privitty-edge health

Cannot connect to API from host¶

Symptom: Connection refused on 127.0.0.1:7200.

Fix: Verify port mapping:

docker port privitty-edged

Expected: 7200/tcp -> 127.0.0.1:7200

Inside the container, the daemon must bind 0.0.0.0:7200 (default Docker CMD).

Provisioning stuck / slow¶

Symptom: Logs hang at "Provisioning via chatmail…"

Causes:

No outbound HTTPS to the relay server
Firewall blocking IMAP (993) or SMTP (587/465)
Relay server temporarily unavailable

Check connectivity:

docker logs privitty-edged 2>&1 | tail -20
curl -s -X POST http://127.0.0.1:7200/rpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"get_connectivity","params":[1],"id":1}'

Ensure egress to chat.privittytech.com (or your custom PRIVITTY_SERVER).

License error (-32001)¶

Symptom:

{"error":{"code":-32001,"message":"Privitty license required…"}}

Fix:

docker exec privitty-edged \
  privitty-edge --accounts /var/lib/privitty license status

docker exec privitty-edged \
  privitty-edge --accounts /var/lib/privitty \
  license activate "https://license.privitty.com/v1/license/TOKEN"

See License Management.

File send fails — path not found¶

Symptom: privitty_send_file returns an error about missing file.

Cause: The file path must exist inside the container, not on the Docker host.

Fix: Mount a volume and use the container path:

-v /host/data:/data:ro
# Then use "/data/report.csv" in RPC calls

Peer join fails¶

Symptom: secure_join errors or progress stuck below 1000.

Checks:

Issue	Fix
Joining own invite link	Use the link from a different account
Invalid link format	Copy the full URL from `invite` output
Network blocked	Ensure both peers can reach the relay
License missing	Activate license on both sides if sending encrypted content

Monitor: curl -N http://127.0.0.1:7200/events for SecurejoinInviterProgress.

SSE stream disconnects¶

Symptom: curl -N /events drops after idle period.

Fix:

A : ping keepalive is sent every 15 seconds — ensure your HTTP client doesn't timeout
Implement reconnect with backoff in production integrations
See Example D · SSE Streaming

Large file not received by peer¶

Symptom: Sender shows success; receiver gets message but no file.

Checks:

Both peers must support QUIC (Privitty Edge + compatible mobile/desktop)
UDP egress may be required for P2P QUIC transfer
Small files (< ~1 MB) use relay — check IMAP connectivity on receiver
Check receiver logs for protocol errors

Data lost after container recreate¶

Symptom: New account address after docker run without volume.

Fix: Always mount a persistent volume:

-v privitty-data:/var/lib/privitty

`"/var/lib/privitty" is not empty` on first start¶

Symptom: License activation succeeds in logs, then:

Fatal: Failed to open accounts directory: "/var/lib/privitty" is not empty

Cause: A previous failed start left license files (privitty.lic, device.uuid, …) in the volume without a Delta Chat accounts.toml.

Fix: Remove the stale volume and start fresh:

docker rm -f privitty-edged
docker volume rm privitty-data

docker run -d \
  --name privitty-edged \
  -e PRIVITTY_PROFILE=factory-gw-01 \
  -e PRIVITTY_LICENSE_URL="https://…" \
  -p 127.0.0.1:7200:7200 \
  -v privitty-data:/var/lib/privitty \
  privitty/edge:latest

Verify:

curl -s http://127.0.0.1:7200/health
docker logs privitty-edged --tail 30

Getting help¶

Email: info@privittytech.com
Include: docker logs, output of license status, and get_connectivity result