Diagnose with `doctor`

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

Check	What it verifies
`store`	The relational store (SQLite or Postgres) opens and passes a health probe.
`vault`	The encrypted KV store accepts a read/write roundtrip.
`integrity`	Vault integrity check succeeds for the active identity.
`identity`	The caller’s identity is registered and authorized.
`providers`	Every bundled and custom provider definition parses.
`connections`	Connection records for the active vault load successfully.
`spec_version`	Server config schema version matches.
`redis`	Present 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

master.key not found

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.

master.key has insecure permissions

vault: ~/.authsome/server/master.key has mode 0644 (expected 0600)

Fix:

chmod 0600 ~/.authsome/server/master.key

provider failed to parse

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.

keyring not available

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 not registered

identity: Unknown identity handle

Run authsome onboard to create a local identity, then complete the Principal claim flow at the URL the daemon prints.

daemon unreachable

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.

Guides

Troubleshooting

Diagnose with `doctor`

Checks performed

Common failures

Verbose logging

Reset to a clean slate

What’s next

OAuth callbacks

Token refresh

​Checks performed

​Common failures

​Verbose logging

​Reset to a clean slate

​What’s next

OAuth callbacks

Token refresh

Checks performed

Common failures

Verbose logging

Reset to a clean slate

What’s next