Skip to main content
authsome doctor is the first command to run when something looks wrong. It calls the daemon’s /api/ready endpoint and reports subsystem status as JSON. 
authsome doctor
A healthy machine returns "status": "ready" and exits with code 0.

​
Checks performed

CheckWhat it verifies
storeThe relational store (SQLite or Postgres) opens and passes a health probe.
vaultThe encrypted KV store accepts a read/write roundtrip.
integrityVault integrity check succeeds for the active identity.
identityThe caller’s identity is registered and authorized.
providersEvery bundled and custom provider definition parses.
connectionsConnection records for the active vault load successfully.
spec_versionServer config schema version matches.
redisPresent only when AUTHSOME_REDIS_URL is set; pings the Redis backend.
Non-fatal observations appear in warnings (for example, no active provider connections yet). Fatal problems appear in issues and set "status": "not_ready".

​
Common failures

vault: Master key not found at ~/.authsome/server/master.key
Causes:
  • You haven’t initialized authsome on this machine. Run authsome onboard to provision the home directory, identity, and master key.
  • You moved or deleted ~/.authsome/server/. If you have a backup, restore it. Without the master key, encrypted records cannot be decrypted.
vault: ~/.authsome/server/master.key has mode 0644 (expected 0600)
Fix:
chmod 0600 ~/.authsome/server/master.key

providers: Provider 'acmecrm' failed to parse: missing required field 'token_url'
A custom provider JSON in ~/.authsome/providers/ is malformed. Open the file, fix the indicated field, and re-run.
vault: Encryption mode is 'keyring' but no keyring backend is available
Causes:
  • On Linux without a graphical session, the keyring library can’t reach a backend. Switch to local file mode by editing ~/.authsome/client/config.json or setting AUTHSOME_MASTER_KEY.
  • A required system package is missing. On Debian/Ubuntu: sudo apt install gnome-keyring.
identity: Unknown identity handle
Run authsome onboard to create a local identity, then complete the Principal claim flow at the URL the daemon prints.
Could not connect to daemon at http://127.0.0.1:7998
The daemon is not running or AUTHSOME_BASE_URL points somewhere wrong. See Daemon issues.

​
Verbose logging

For deeper inspection of any command, enable verbose logging: 
authsome --verbose login github
DEBUG logs go to stderr and to the rotating log file at ~/.authsome/client/logs/authsome.log. Inspect the log: 
tail -f ~/.authsome/client/logs/authsome.log

​
Reset to a clean slate

If your install is irrecoverably broken and you don’t have any credentials to preserve: 
rm -rf ~/.authsome
authsome onboard
This destroys every stored credential. You will need to log in to every provider again.

​
What’s next

OAuth callbacks

Diagnose redirect_uri_mismatch, port-in-use, and timeout errors.

Token refresh

Why a token failed to refresh and what to do.