> ## Documentation Index
> Fetch the complete documentation index at: https://authsome.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose with `doctor`

> Run health checks on the daemon, vault, and provider parsing, and read the output.

`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.

```bash theme={null}
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

<AccordionGroup>
  <Accordion title="master.key not found" icon="key">
    ```text theme={null}
    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.
  </Accordion>

  <Accordion title="master.key has insecure permissions" icon="lock-open">
    ```text theme={null}
    vault: ~/.authsome/server/master.key has mode 0644 (expected 0600)
    ```

    Fix:

    ```bash theme={null}
    chmod 0600 ~/.authsome/server/master.key
    ```
  </Accordion>

  <Accordion title="provider failed to parse" icon="file-exclamation">
    ```text theme={null}
    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.
  </Accordion>

  <Accordion title="keyring not available" icon="vault">
    ```text theme={null}
    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`.
  </Accordion>

  <Accordion title="identity not registered" icon="user">
    ```text theme={null}
    identity: Unknown identity handle
    ```

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

  <Accordion title="daemon unreachable" icon="server">
    ```text theme={null}
    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](/troubleshooting/daemon-issues).
  </Accordion>
</AccordionGroup>

## Verbose logging

For deeper inspection of any command, enable verbose logging:

```bash theme={null}
authsome --verbose login github
```

DEBUG logs go to stderr and to the rotating log file at `~/.authsome/client/logs/authsome.log`. Inspect the log:

```bash theme={null}
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:

```bash theme={null}
rm -rf ~/.authsome
authsome onboard
```

This destroys every stored credential. You will need to log in to every provider again.

## What's next

<Columns cols={2}>
  <Card title="OAuth callbacks" icon="link" href="/troubleshooting/oauth-callbacks">
    Diagnose `redirect_uri_mismatch`, port-in-use, and timeout errors.
  </Card>

  <Card title="Token refresh" icon="rotate" href="/troubleshooting/token-refresh">
    Why a token failed to refresh and what to do.
  </Card>
</Columns>