Skip to content
AccessVault Docs

Troubleshooting

Claude gets “HTTP 401 Unauthorized” after I restarted AccessVault

Expected — this is the most common issue. The bearer token that authenticates the sidecar to the app is regenerated on every app launch, so a claude mcp add command you ran yesterday holds yesterday’s token. Fix: with the connection active, click Copy command in the MCP sidecar panel and run it again to re-register with the fresh token.

(For scripting: the current session’s token, port, and PID are written to ~/Library/Application Support/com.accessvault.dev/runtime.json on each launch.)

Claude gets “Error: http client error: … connection refused”

The sidecar can’t reach AccessVault — the app isn’t running (or is listening on a different port than the registered --api-url). Launch AccessVault and retry. The sidecar has no database access of its own; it only works while the app is up.

Claude gets “api error (status 409): not connected to a database”

The app is running but the connection isn’t active. Select it in the sidebar and click Connect.

Tools aren’t showing up in Claude

  • Check the tool is Enabled in the Catalog tab — disabled tools are hidden from Claude. The sidecar hot-reloads the catalog, so an enable takes effect within moments.
  • If you edited the catalog file by hand and made it invalid, the sidecar logs a warning and keeps serving the last valid version — fix the file or edit through the app. An invalid catalog at sidecar startup is fatal: the sidecar exits, and Claude reports the server as failed.

Port 9876 is taken

The app’s HTTP API defaults to port 9876. Launch AccessVault with the ACCESSVAULT_PORT environment variable set to change it — then re-run Copy command, since the registered --api-url embeds the port.

SSH tunnel keeps dropping

Dead tunnels are detected via keepalives (default: every 30 seconds, dead after 3 missed — roughly 90 seconds) and rebuilt automatically on the next query or command; you’ll see a toast and a builtin:ssh_reconnect entry in the audit log. If reconnects themselves fail, run Test Connection in the connection form — it reports the SSH step separately from the database step, so you can tell a bastion problem from a database problem. Rotated SSH credentials are re-read from the Keychain on reconnect, but a changed bastion hostname or port means editing the connection.

”pg_stat_statements is not installed”

The Monitoring slow-queries section and all of Privilege Analysis need the pg_stat_statements extension. The Privileges tab offers an Enable Extension button (CREATE EXTENSION IF NOT EXISTS), which needs a database user with rights to create extensions. On most servers the module must also be in shared_preload_libraries (a server restart), and stats only accumulate from that point — give it time before trusting “unused” verdicts.

Connection test fails

  • Remote databases usually want TLS set to require; some managed providers refuse non-TLS connections entirely.
  • Behind a bastion, remember the Host/Port fields describe the database as seen from the bastion (often a private address), not from your machine — see SSH Tunneling.
  • The failed-test message shows the raw driver error, which usually names the culprit (authentication, DNS, refused connection).

macOS won’t open the app

Beta builds aren’t code-signed yet. Right-click the app in Applications and choose Open — see Installation.

Still stuck? The audit log records every operation including failures — the error messages there are often more specific than what the UI surfaces.