# How the wacli doctor Command Diagnoses Connection and Authentication Issues

> Troubleshoot wacli connection and authentication problems with the doctor command. This diagnostic tool checks your local store, authentication, and network status to resolve errors.

- Repository: [Peter Steinberger/wacli](https://github.com/steipete/wacli)
- Tags: how-to-guide
- Published: 2026-04-17

---

**The `wacli doctor` command runs a comprehensive diagnostic suite that checks the local store directory, file lock status, WhatsApp authentication state, and optional live network connectivity to pinpoint exactly why `wacli` commands are failing.**

The `wacli doctor` command is a built-in diagnostic tool in the [steipete/wacli](https://github.com/steipete/wacli) repository that inspects the most common failure points when the CLI tries to communicate with WhatsApp. It validates the **store directory**, **file locks**, **authentication status**, and **network connectivity** without requiring a full sync operation. By running these checks in sequence, the command provides a concise snapshot of the runtime state that explains why subsequent `wacli send`, `wacli sync`, or `wacli search` commands might fail.

## Diagnostic Checks Performed by wacli doctor

The diagnostic logic is implemented in [`cmd/wacli/doctor.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/doctor.go). The command constructs the application using `newApp(..., needLock=true, allowUnauthed=true)` from [`cmd/wacli/root.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/root.go), which allows the diagnostic to run even when the store is not yet authenticated.

### Store Location and Lock Status

First, the command resolves the **data directory** (defaulting to `~/.config/wacli`) using `config.DefaultStoreDir()` from [`internal/config/config.go`](https://github.com/steipete/wacli/blob/main/internal/config/config.go). It displays the absolute path to help users verify they are operating on the correct store.

Next, it checks the **lock status** by reading a `LOCK` file in the store directory. Using the `lock.Acquire` logic from [`internal/lock/lock.go`](https://github.com/steipete/wacli/blob/main/internal/lock/lock.go), it attempts to acquire a lock. If another `wacli` process (such as `wacli sync`) is currently running, the lock acquisition fails and the doctor reports the lock holder's PID and command. This immediately identifies concurrency conflicts that would block write operations.

### Authentication Verification

The command calls `a.OpenWA()` followed by `a.WA().IsAuthed()` to verify that a valid WhatsApp session exists. This check determines whether the device has completed the QR-code pairing process and whether the session credentials are still valid. If authentication fails, the doctor reports `AUTHENTICATED: false`, indicating that the user needs to re-run `wacli login` or check for session expiry.

### Optional Live Connection Test

When invoked with the `--connect` flag, the doctor attempts to open a live WebSocket connection to WhatsApp using `a.Connect`. This test reveals network-level issues, proxy misconfigurations, or session-expiry problems that only manifest during actual communication. A successful connection displays `CONNECTED: true`, while failures surface specific error messages from the underlying WhatsApp Web library.

### Full-Text Search (FTS) Availability

For users experiencing search failures, the command queries `a.DB().HasFTS()` to confirm that the SQLite **FTS5** extension is loaded. This diagnostic is crucial because the `wacli search` command depends on FTS5 for full-text indexing. If the extension is missing, the doctor reports `FTS5: false`, explaining why search operations return errors.

### Structured JSON Output

Automation and CI pipelines can consume the diagnostic results by passing the `--json` flag. The command emits a structured JSON object containing fields such as `store_dir`, `lock_held`, `authenticated`, `connected`, and `fts_enabled`. This format enables programmatic health checks and monitoring without parsing human-readable text.

## Practical Usage Examples

### Basic Health Check

Run the standard diagnostic to see the current state of your wacli installation:

```bash
wacli doctor

```

**Typical output:**

```

STORE   /home/user/.config/wacli
LOCKED  false
AUTHENTICATED  true
CONNECTED  false
FTS5    true

```

This indicates a healthy store that is authenticated but not currently connected to WhatsApp.

### JSON-Formatted Report for Automation

Integrate health checks into monitoring scripts using the JSON output:

```bash
wacli doctor --json

```

```json
{
  "store_dir": "/home/user/.config/wacli",
  "lock_held": false,
  "authenticated": true,
  "connected": false,
  "fts_enabled": true
}

```

### Test Live Connectivity

Diagnose network or session issues by forcing a connection attempt:

```bash
wacli doctor --connect

```

If the session is valid and the network is accessible, the output includes `CONNECTED: true`. Connection failures surface specific error messages indicating whether the issue is network-related, proxy-related, or due to an expired session.

### Diagnosing a Locked Store

When another wacli process is running, the doctor reports:

```

LOCKED  true
LOCK_INFO  sync running (PID 12345)
Tip: stop the running `wacli sync` before running write operations.

```

This immediately identifies which process holds the lock and advises the user to terminate it before attempting write operations like `wacli send`.

## Summary

- The **`wacli doctor`** command provides a comprehensive diagnostic snapshot by checking the **store directory**, **file locks**, **authentication status**, and **network connectivity**.
- It uses `newApp(..., needLock=true, allowUnauthed=true)` from [`cmd/wacli/root.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/root.go) to ensure diagnostics can run even on unauthenticated stores.
- Key implementation files include [`cmd/wacli/doctor.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/doctor.go) for the diagnostic logic, [`internal/lock/lock.go`](https://github.com/steipete/wacli/blob/main/internal/lock/lock.go) for lock management, and [`internal/config/config.go`](https://github.com/steipete/wacli/blob/main/internal/config/config.go) for store path resolution.
- The **`--connect`** flag tests live WhatsApp WebSocket connections, while **`--json`** enables machine-readable output for CI pipelines.
- By reporting **FTS5** availability, the command also explains search functionality failures.

## Frequently Asked Questions

### What does wacli doctor check first when diagnosing issues?

The command first resolves and displays the **store directory** using `config.DefaultStoreDir()` from [`internal/config/config.go`](https://github.com/steipete/wacli/blob/main/internal/config/config.go). It then immediately checks the **lock status** by attempting to acquire a lock via `lock.Acquire` in [`internal/lock/lock.go`](https://github.com/steipete/wacli/blob/main/internal/lock/lock.go), reporting if another process is currently using the store.

### Can wacli doctor run if I haven't authenticated yet?

Yes. The `doctor` command explicitly initializes the application with `allowUnauthed=true` in the `newApp` call from [`cmd/wacli/root.go`](https://github.com/steipete/wacli/blob/main/cmd/wacli/root.go). This allows the diagnostic to inspect the store location, lock status, and FTS availability even when no WhatsApp session exists, though it will report `authenticated: false`.

### How do I test if my WhatsApp connection is working with wacli doctor?

Pass the **`--connect`** flag to the command. This triggers a call to `a.Connect` which attempts to open a live WebSocket connection to WhatsApp. If successful, the output shows `connected: true`; if the session expired or network issues exist, the command surfaces the specific error message.

### What does the FTS5 check in wacli doctor indicate?

The **FTS5** check queries `a.DB().HasFTS()` to verify that the SQLite FTS5 extension is loaded in the store database. This is critical because the `wacli search` command depends on FTS5 for full-text indexing. If the doctor reports `fts_enabled: false`, it explains why search operations are failing and indicates a missing SQLite extension.