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

# Troubleshoot Air-Gapped Devin: doctor Runbook

> Runbook for devin airgap doctor on the air-gapped Devin CLI and Desktop: what each check verifies, what pass, warn, and FAIL mean, and what to send to support.

> [!NOTE]
>
> This documentation is for the federal deployments of Devin. [Back to Devin Docs](/get-started/devin-intro)

`devin airgap doctor` is the first thing to run when the CLI or Desktop does not start, cannot reach a model, or shows an error code. It runs every local and network check the agent depends on, prints one line per check, and exits nonzero if anything fails. This page explains each check and what to do about it, then describes what to collect for a support request.

***

## Run doctor

Run it as the user who will use Devin, in the same environment (the API-key variables must be set in that shell):

```sh theme={null}
devin airgap doctor
```

```text theme={null}
pass  license                                seat alice@example.gov (account acme), expires 2027-03-01
pass  models file path                       /etc/devin/models.json
pass  config dir writable                    /home/alice/.config/devin/cli-federal
pass  data dir writable                      /home/alice/.local/share/devin/cli-federal
pass  CA bundle                              not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)
pass  models file parse                      1 model(s) configured
pass  model 'llama-3.3-70b': API key env var  LOCAL_LLAMA_API_KEY is set
pass  custom subagent profiles               none configured
pass  model 'llama-3.3-70b': endpoint reachability  GET https://models.internal:8000/v1/models -> 200 OK
pass  model 'llama-3.3-70b': inference conformance  POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)

10 check(s): 10 passed, 0 warning(s), 0 failure(s)
```

Each line is `<status>  <check>  <detail>`. Coded failures and warnings prefix the detail with the [error code](/federal/air-gapped/error-codes), for example `FAIL  model 'llama-3.3-70b': endpoint reachability  NET003: ...`.

| Status | Meaning | Exit status |
| - | - | - |
| `pass` | The check succeeded. | |
| `warn` | Devin will run, but something needs attention soon (license expiring, `/models` not implemented, probe skipped). | `0` |
| `FAIL` | Devin will not work correctly until this is fixed. | nonzero, with `doctor found N failing check(s)` |

For automation, `--json` prints `{"ok": <bool>, "checks": [...]}` where each check has `check`, `status` (`pass`, `warn`, `fail`), and `detail`, plus `code` on coded warnings and failures and `latency_ms` on a passing inference probe:

```sh theme={null}
devin airgap doctor --json
```

```json theme={null}
{
  "ok": true,
  "checks": [
    {
      "check": "license",
      "status": "pass",
      "detail": "seat alice@example.gov (account acme), expires 2027-03-01"
    },
    {
      "check": "model 'llama-3.3-70b': inference conformance",
      "status": "pass",
      "detail": "POST https://models.internal:8000/v1/chat/completions -> 200 OK (412 ms)",
      "latency_ms": 412
    }
  ]
}
```

Desktop uses the same bundled CLI, so run doctor from a terminal on the Desktop host to diagnose Desktop problems too.

## Check reference

Checks run in the order below. Later checks that depend on an earlier failure are skipped rather than repeated: if the models file cannot be found, there is no `models file parse` line and no endpoint probes.

### `license`

Loads and verifies the license file (see [License](/federal/air-gapped/license)).

| Result | Detail | Action |
| - | - | - |
| `pass` | `seat <label> (account <id>), expires <YYYY-MM-DD>` | None. |
| `warn` | `... (<n> day(s) left) — contact your administrator to renew it` when fewer than 30 days remain; `(less than a day left)`; or `already expired (within the clock-skew grace period)` | Renew and replace the license before the 24-hour grace period ends. |
| `FAIL` | `LIC00n: <message>` followed by `Checked <path> — install a valid license there or point DEVIN_LICENSE_FILE at one.` | Follow the `LIC` row in [Error codes](/federal/air-gapped/error-codes#lic-license). |

### `models file path`

Resolves the models file location (`/etc/devin/models.json`, `C:\ProgramData\Devin\models.json` on Windows, or `DEVIN_MODELS_FILE`) and confirms a file exists there.

| Result | Action |
| - | - |
| `pass` with the resolved path | None. |
| `FAIL CFG003` | Install the models file or fix the `DEVIN_MODELS_FILE` value. All models-file and endpoint checks are skipped. |

### `config dir writable` and `data dir writable`

Creates the product config and data directories if needed and writes a probe file to each.

| Result | Action |
| - | - |
| `pass` with the directory path | None. |
| `FAIL CFG001` | The detail says whether the directory could not be resolved, created, or written. Fix ownership and permissions for the user running Devin, or set `XDG_CONFIG_HOME` / `XDG_DATA_HOME` to a writable location. On Windows the CLI does not read `XDG_*`; fix the permissions on `%APPDATA%\devin\`. |

### `CA bundle`

Reports whether `DEVIN_CA_BUNDLE` is set and loads it.

| Result | Detail | Action |
| - | - | - |
| `pass` | `not configured (OS trust store only; set DEVIN_CA_BUNDLE to add a private CA)` | None, unless your endpoints use a private CA. |
| `pass` | `<path> (<n> certificate(s))` | None. |
| `FAIL CFG004` | Why the file could not be loaded | Fix the path or the PEM contents; see [Network and certificates](/federal/air-gapped/network-and-certificates). |

### `models file parse` and `model '<name>': API key env var`

Parses the models file with the same validator as `devin models validate`, then checks that each model's `api_key.env` variable is set in the current environment.

| Result | Action |
| - | - |
| `pass  models file parse  <n> model(s) configured` | None. |
| `FAIL  models file parse  <message> (run devin models validate for structured MDL diagnostics)` | Run `devin models validate` and fix each `MDL` code; see [Models file](/federal/air-gapped/models-file). Endpoint probes are skipped. |
| `pass  model '<name>': API key env var  <VAR> is set` | None. |
| `FAIL CFG002  environment variable '<VAR>' (referenced by api_key.env) is not set` | Export the variable in this shell, or for Desktop add it to `devin.acp.agentEnv`; see [API key environment variables](/federal/air-gapped/models-file#api-key-environment-variables). The endpoint probes for that model are skipped with a `warn`. |

### `custom subagent profiles`

Lists custom subagent definitions from `agents/**/AGENT.md`. `none configured` or `<n> profile(s) loaded` passes; `CFG005` names a definition that could not be parsed. This check is shared with the standard `devin doctor` and is unrelated to the air-gapped configuration.

### `model '<name>': endpoint reachability`

Sends `GET {base_url}/models` with the model's API key, using a 10-second timeout and the same TLS configuration inference uses.

| Result | Detail | Action |
| - | - | - |
| `pass` | `GET <url> -> 200 OK` | None. If the detail adds `(trusted only via DEVIN_CA_BUNDLE — the OS trust store alone rejects this endpoint's certificate)`, the bundle is load-bearing: keep it configured on every host. |
| `warn NET004` | `GET <url> -> 404 Not Found (server may not implement /models)` | None; the endpoint is reachable and the inference probe below is the real test. |
| `warn CFG002` | `skipped: API key env var '<VAR>' is not set` | Set the variable (see above). |
| `FAIL NET006` | `GET <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'` | The variable is set but its value is wrong for this endpoint. |
| `FAIL NET004` | `GET <url> -> <status>` | Check the endpoint's logs and the `base_url` path. |
| `FAIL NET001` / `NET002` / `NET005` | DNS, TCP, or timeout error chain | Check name resolution, firewall and proxy rules, and endpoint health from the same workstation. |
| `FAIL NET003` | TLS error chain, then the certificate the server presented (subject, issuer, expiry), then either `TLS failed despite the configured DEVIN_CA_BUNDLE (<path>) — verify the bundle contains this endpoint's CA` or `if this endpoint uses a private CA, set DEVIN_CA_BUNDLE=/path/to/ca.pem` | Compare the printed issuer with the certificates in your bundle; see [Network and certificates](/federal/air-gapped/network-and-certificates). |

### `model '<name>': inference conformance`

Skipped when reachability failed at the transport level. Sends a one-token request to prove the endpoint speaks the configured API: `POST {base_url}/chat/completions` with `max_tokens: 1` for `chat_completions`, or `POST {base_url}/responses` with `max_output_tokens: 16` for `responses`.

| Result | Detail | Action |
| - | - | - |
| `pass` | `POST <url> -> 200 OK (<n> ms)` | None. The latency is a useful baseline for later comparisons. |
| `FAIL NET006` | `POST <url> -> 401 Unauthorized: endpoint rejected the API key from '<VAR>'` | Fix the key. |
| `FAIL NET004` | `POST <url> -> <status>: <first 200 characters of the response body>` | The body usually names the problem: unknown model name (the request uses the `name` from your models file, which must match what the server serves), wrong `api` value for this server, or a server-side error. |
| `FAIL NET00n` | Transport error chain | As for reachability. |

## Common problems

| Symptom | Likely cause | Where to look |
| - | - | - |
| Doctor passes in a terminal but Desktop cannot reach the model | Desktop's bundled agent does not inherit your shell environment, so the API-key variable is unset | [API key environment variables](/federal/air-gapped/models-file#api-key-environment-variables) |
| Every user on a host passes except one | Per-user state: permissions on `~/.config/devin` or `~/.local/share/devin` (`%APPDATA%\devin` on Windows), or a stale `sso_tokens.toml` (`IDP006`) | [On-disk formats](/federal/air-gapped/on-disk-formats) |
| `devin auth login` succeeds but sessions end after a while | Revalidation failed: the user was removed from `required_group` or the IdP session was revoked | [SSO](/federal/air-gapped/sso#revalidation-in-running-sessions) and the `sso_revalidation_failed` audit event |
| `NET003` only on some hosts | `DEVIN_CA_BUNDLE` not set, or a different bundle, on those hosts | [Network and certificates](/federal/air-gapped/network-and-certificates) |
| `LIC004` after installing an update, or on a new environment | Build and license come from different environments, or a key rotation | [License: check the key ID](/federal/air-gapped/license#check-the-key-id) |
| `MDL014` when saving models in Desktop | The models file is owned by root or another user (on Windows, by an administrator while you are a standard user) | Edit the file on disk as its owner |

## What to send to support

Collect the following on the affected workstation. Review each file before sending it; none of them is uploaded automatically.

1. The doctor output:

   ```sh theme={null}
   devin airgap doctor --json > doctor.json
   ```

   ```text theme={null}
   (no output; the command exits nonzero if a check failed)
   ```

   The detail strings contain your endpoint URLs and hostnames but never API-key values.

2. The redacted diagnostics report:

   ```sh theme={null}
   devin diagnostics --output devin-diagnostics.txt
   ```

   ```text theme={null}
   Diagnostics written to devin-diagnostics.txt
   The report is plain text and stays on this machine; review it before sharing.
   ```

   The report records versions, whether each configuration file exists and parses, model names, whether each API-key variable is set, and audit-log statistics. It never contains prompts, code, file contents, secret values, endpoint URLs, or environment-variable values.

3. The exact error message shown to the user, including its code, and the output of `devin --version`.

4. For SSO problems, the relevant `auth` events from the [audit log](/federal/air-gapped/on-disk-formats#audit-log) (`error_code` and `action` fields) and the matching entries from your IdP's logs.

Do not send the license file, the API-key values, `sso_tokens.toml`, or `sessions.db`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.