Troubleshooting

Start with Settings → Diagnostics (or wharfbase doctor). It checks these and says what to fix:

• Docker and the socket-guard;
• the networks;
• the data folder and free space;
• the master key;
• the clock.

wharfbase doctor --bundle writes a redacted zip (no passwords, no secret values) to attach to a support request. Every error in the UI, the API and wb has a code: the error codes say what each one means and what to do.

Installing and starting

• “Docker API unreachable” in the logs:
  • The socket-guard isn’t running (wharfbase status), or the Docker socket isn’t at /var/run/docker.sock.
  • For rootless Docker, the installer writes the right path as WB_DOCKER_SOCKET in .env.
• Lost the setup token: wharfbase setup-token prints it again, until setup is done.
• Wharfbase won’t start: “The master key does not match this data directory”, or the key “must be 32 random bytes”:
  • The key file was changed or damaged. Wharfbase refuses to start rather than make a new key, and touches nothing.
  • Put back the key you backed up and start it again.
• “This data folder was used by a newer Wharfbase” (SCHEMA_TOO_NEW): you started an older release on newer data. Upgrade again, or see Upgrading to go back.

Finding and reaching databases

• A database is missing:
  • Is its container running, and not labelled wharfbase.enable=false?
  • An unusual image is still found by its ports; wharfbase.engine and wharfbase.port labels settle it.
  • Databases outside Docker need the host scan, or an admin adds them through the API: POST /api/v1/databases/manual with the engine, a name and the host and port (or a file path for SQLite).
• “needs network”: the attach mode is Ask or Off. Use Join network on the database, or set Auto (or Relays) under Settings → Discovery (Networks).
• “host config needed”: a database on the host listens on 127.0.0.1 only. The Reachability tab shows the line to change.
• Docker restarted during a scan: the scan says it failed, and the databases keep their last known state. The next scan, which starts by itself when Docker is back, catches up.

Connecting

• DB_AUTH_FAILED:
  • The database user or password is wrong (not your Wharfbase password).
  • Use the password from the container in the connect dialog reads it from the container’s environment, once and audited (with WB_SECRET_HINTS=on-demand, the default).
• DB_PERMISSION_DENIED: the database user lacks a grant. Each engine’s page lists what each feature needs.
• DB_TLS_ERROR: set the connection’s TLS mode to match the server (Edit connection → TLS).
• DB_LOCKED_BY_PLAN: after a downgrade, the owner chooses which databases stay active under Settings → License.

Using it

• A query stops with DB_TIMEOUT: it ran past the statement timeout (30 s, WB_STATEMENT_TIMEOUT_MS). Add a filter or a LIMIT, or export instead.
• A query ends with a connection error:
  • The database restarted, or someone killed the session.
  • The next query reconnects by itself.
• DB_READ_ONLY: the connection is read-only. The message says why: its setting, the production guard, your role, or a per-database permission.
• A server shows offline (Pro): its agent stopped or can’t reach the hub. Run docker logs wharfbase-agent on that server; the agent reconnects by itself.

Space and memory

• “Wharfbase’s data volume has only … MB free, so changes are paused” (STORAGE_FULL):
  • Below 64 MB free (WB_MIN_FREE_MB), Wharfbase stops saving changes before a write could fail halfway.
  • Browsing, signing in and deleting old backups still work.
  • Free some space (old backups and exports are in the data folder) and carry on. Nothing needs a restart.
• Memory: a running instance uses about 150 to 200 MB. GET /api/v1/system/stats (admins) shows memory, open handles and database sessions, to attach to a report.