---
title: Troubleshooting
description: Common errors and platform-specific setup
icon: LifeBuoy
---

Start with `earl doctor` — it catches most configuration issues:

```bash
earl doctor
```

## Common Errors

### `Request blocked by network allowlist`

The request URL doesn't match any `[[network.allow]]` rule. Add an entry for the host:

```toml
[[network.allow]]
scheme = "https"
host = "api.github.com"
port = 443
path_prefix = "/"
```

### `Secret 'provider.key' not found`

The template requires a secret that isn't stored. Set it:

```bash
earl secrets set <key>
```

Use `earl secrets list` to see stored keys.

### `Authentication profile 'name' not found`

The template references an OAuth2 profile not defined in `config.toml`:

```toml
[auth.profiles.name]
flow = "device_code"
# ...
```

### `unsupported template URL scheme`

`earl templates install` only accepts local `.hcl` file paths or `http://`/`https://` URLs.

### `template source path '...' was not found or is not a file`

The path doesn't exist or points to a directory. Pass a path to a `.hcl` file.

### `template file must end with .hcl`

Rename the source file to end in `.hcl`.

### `Tool '...' is write-mode; restart the MCP server with --yes`

The MCP server blocks write-mode tools by default. Restart with `--yes`:

```bash
earl mcp stdio --yes
```

### `CLI command '...' is not in allow_cli_commands`

A CLI-protocol template tried to run a command not in your allowlist. Add it to config:

```toml
[network]
allow_cli_commands = ["cargo"]
```

## Platform Notes

### Linux

Earl uses the [Secret Service](https://specifications.freedesktop.org/secret-service/) API for secret storage. A compatible daemon is required:

- **GNOME:** `gnome-keyring`
- **KDE:** `kwallet`
- **Other:** `keepassxc` with Secret Service integration enabled

In headless environments (servers, CI), start a session D-Bus and unlock the keyring programmatically.

### macOS

Uses the native Keychain. No additional setup required.

### Windows

Uses the native Credential Manager. No additional setup required.
