---
title: "Diagnostic Tool (doctor)"
description: "Run health checks to diagnose configuration and tooling issues."
---

<Tip>
  Run `doctor` first whenever you experience unexpected behavior. It quickly surfaces missing directories, unparseable recipes, a stale lockfile, and absent tooling before you dig deeper.
</Tip>

The `doctor` command inspects your local setup and reports the status of each check:

```bash
fp-appimage-updater doctor
```

## Checks performed

| Check | What it verifies |
|---|---|
| `config_dir` | The configuration directory exists |
| `apps_dir` | The apps subdirectory exists |
| `global_config` | The global `config.yml` file is present and parseable |
| `state_dir` | The state directory is accessible |
| `parsed_app_recipes` | Number of recipe files that loaded successfully |
| `invalid_app_recipes` | Number of recipe files that failed to parse |
| `process_lock` | Whether the current lockfile is missing, active, or stale |
| `github_api` | GitHub API connectivity and token validity |

Each check reports either `ok` or `warn`. A `warn` result does not stop the tool from running, but it may explain unexpected behavior.

`process_lock` reports `warn` when the lockfile looks stale or malformed. That usually means a previous run exited unexpectedly, and the next run can clean it up.

`doctor` checks local files, local tools, and performs a lightweight request to the GitHub API to verify your rate limit and token status.

<Note>
  Add `--json` to get machine-readable output suitable for scripting or monitoring:

  ```bash
  fp-appimage-updater doctor --json
  ```
</Note>

## Common issues

**Recipe files failed to parse**

Run `validate` to identify which files have errors and what the parse error is:

```bash
fp-appimage-updater validate
```

To check a single recipe by name:

```bash
fp-appimage-updater validate <app-name>
```

---

**Config directory not found**

Initialize the configuration directory with:

```bash
fp-appimage-updater init --global
```

This creates the expected directory structure and a starter `config.yml`.
