> ## Documentation Index
> Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting
> Diagnose Condor and Hummingbot API connection problems, and lock down the message broker
Before working through the cases below, run **`make doctor`** in the Condor directory — it covers most of what follows and names the fix directly. On the API host, `hummingbot-api` ships its own **`make doctor`**: it checks the containers, which ports are on a public interface, the broker's credentials, Tailscale's tailnet *and* serve status, and whether the API answers an authenticated request.
## Connection issues
This is where most problems land: Condor showing **Offline**, *Cannot reach server*, *Connection timeout*, or **Auth Error** somewhere in the UI. Work through this section first.
Condor talks to the **Hummingbot API** over HTTP using the **host**, **port**, **username**, and **password** stored for each server (see **`/servers`** in Telegram or `condor/config.yml`). Status checks call `http://{host}:{port}` and list accounts — a failure to connect surfaces as **Offline**, a failure to authenticate as **Auth Error**.
1. **Is the API stack up?** On the machine where Docker runs the API: `docker compose ps` (from the `hummingbot-api` repo directory). You want the API container healthy and port **8000** (default) listening.
2. **Smoke test from the Condor host:**
```bash theme={null}
curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:8000/docs # same machine
curl -u USER:PASS http://hummingbot-api:8000/ # over Tailscale
```
You should get **200**. If this fails, Condor will show offline until the API is reachable — everything below is about getting this curl to succeed.
3. **Wrong host for your layout**
* API and Condor on the **same** machine: `host` is usually `localhost` or `127.0.0.1`.
* API on a **different** host or VPS: use **`hummingbot-api`** (MagicDNS) when Tailscale is enabled — not a public IP and not `localhost` (localhost would point at the Condor machine itself).
* **Docker Desktop / WSL:** If Condor runs in one environment and the API in another, `localhost` may not cross namespaces; use the host gateway IP (`host.docker.internal` on Mac/Windows) or publish ports and use the reachable address from Condor's network namespace.
4. **Credentials:** **Auth Error** means HTTP **401** — username/password in **`/servers`** must match the API's HTTP basic auth (the deploy flow syncs `config.yml` with `hummingbot-api/.env` when both are installed together; if you changed one side, align the other or re-save in **`/servers`**). The setup wizard requires real credentials and no longer seeds `config.yml` with a default pair, so an entry with a blank or placeholder password means it was never filled in — `make doctor` flags that case by name.
Just fixed the API and the server still shows **Offline**? Condor caches an unreachable server for a short cooldown window and won't retry on every request — give it a few seconds, or open **`/servers`** and check the entry again to force a fresh check.
### Tailscale-specific problems
Prefer Tailscale over opening port **8000** on a public firewall — see [Secure Remote Access with Tailscale](/getting-started/installing#secure-remote-access-with-tailscale). If you must use a public IP instead, allow inbound **8000** only from the Condor host.
| Problem | Try this |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name `hummingbot-api` does not resolve | Enable **MagicDNS** in [Tailscale DNS settings](https://login.tailscale.com/admin/dns) |
| `curl: (6) Could not resolve host` | MagicDNS hasn't been accepted on this device yet — run `sudo tailscale up --accept-dns=true` |
| Could not connect / connection timeout | Tailscale isn't actually up on this machine. Run `tailscale status` — if it errors or the peer is missing, run `sudo tailscale up` (macOS: open the Tailscale app and log in), then retry the curl test above |
| `curl` succeeds but Condor still shows Offline | The host in **`/servers`** doesn't match what you just tested, or the credentials weren't re-saved after an `.env` change — re-check both against `config.yml` |
| Two machines signed into different accounts | Both devices must be on the **same tailnet** — check the [admin console](https://login.tailscale.com/admin/machines) lists both, not just one |
| `tailscale up` warns something already owns `tailscale0` | Hummingbot API's own Tailscale sidecar is already holding that device on this machine. Set `TAILSCALE_MODE=host` or `TAILSCALE_MODE=sidecar` in `hummingbot-api/.env` so the two don't contend for it |
| Two `hummingbot-api` entries in your tailnet (`hummingbot-api`, `hummingbot-api-1`) | A second API deployment registered under the same base name — they are different machines, and connecting to the wrong one looks exactly like a bad password. Check the [admin console](https://login.tailscale.com/admin/machines) for both and point `/servers` at the right one |
| Auth key rejected | Key must start with `tskey-auth-`; generate a new one if it expired |
| Asked for a `tskey-auth-...` key unexpectedly | The installer only skips this question when Tailscale is **already connected** before you run it. Ctrl+C, finish `tailscale up` first, then re-run `make setup` |
| Connection refused | On the API server: `make tailscale-status` and `make deploy` again |
| Login fails (401) | Use the same username/password as in the API `.env` — a mistyped password is the usual cause, since it isn't echoed as you type |
| Still reachable on public IP | Remove port **8000** from your cloud provider's firewall / security group |
See also: [Hummingbot API Tailscale guide](https://hummingbot.org/hummingbot-api/tailscale/)
## Other issues
### Won't start
Telegram mode requires a token, and Condor refuses to start without one rather than quietly falling back to the unauthenticated local dashboard.
Run `make setup` and either re-enter the bot token, or choose **Local** mode if you do not want a bot at all. `make doctor` reports the same thing before you try to start.
Both come from the same check: `ADMIN_USER_ID` in `.env` must be a positive integer, and in **Local** mode that id must also exist as an approved user in `config.yml`.
* **Not a valid user id:** something non-numeric ended up in `ADMIN_USER_ID` — fix it in `.env` or run `make setup` again.
* **"Local mode logs in as user N ... but that user is not an approved user in config.yml":** the id in `.env` and the id `config.yml` expects have drifted apart, usually after editing one file by hand. Re-run `make setup` so both are written together, rather than editing either file in isolation.
`CONFIG_PASSWORD` encrypts every exchange credential the API holds, and it's fixed the first time the API ever starts — a verification file is written then, and every later boot checks the current `.env` value against it.
Editing `CONFIG_PASSWORD` in `.env` after that first run doesn't rotate anything; it just fails this check. Restore the original password, or if it's genuinely lost, delete `bots/credentials/` and re-add every exchange API key — there's no way to recover the old encrypted credentials without the original password.
Something else is already listening on the port Condor or the API is trying to bind — a previous instance that didn't fully stop, or an unrelated process. Neither side currently checks for this before binding, so the error is a raw one from the process crashing, not a friendly message.
Find and stop whatever holds the port (`lsof -i :8088` for the dashboard, `:8000` for the API), or change the port — `WEB_HOST`/dashboard port in Condor's `.env`, `API_BIND` in `hummingbot-api/.env`.
### Telegram and servers
1. **Confirm the process is running**
* *Quick Start / deploy:* `tmux attach -t condor` and look for tracebacks or exit messages.
* *Manual install:* Check the terminal where `make run` is running.
2. **Check `condor/.env`** on the machine that runs Condor: `TELEGRAM_TOKEN` must match [@BotFather](https://t.me/botfather), and `ADMIN_USER_ID` must be your numeric Telegram user id (from [@userinfobot](https://t.me/userinfobot)).
3. **Access still pending:** New users must be approved. An admin should use **`/admin`** (or the admin flow from **`/start`**) to approve you.
4. **Deploy installer hint:** If admins never see *"Condor is online and ready."*, attach to tmux (above) and fix errors shown there; the installer also reminds you to verify `.env` when that message is missing.
* **`/servers`** shows *No servers configured* until at least one entry exists in **`condor/config.yml`** under `servers:` (and users need **access** to a server — admins own new entries; others must be **shared**).
* **Server not found** in the UI usually means the configured server name does not exist anymore (typo after edit, or deleted entry) — open **`/servers`**, pick a valid server, or add one again.
* **No servers available** (errors when running commands) often means your user has no server shared with them — ask an **owner** admin to share a server with your Telegram user id.
* After **Manual install**, you must add the real API URL (and auth) via **`/servers`** if `config.yml` was not pre-filled.
That is intended. Local mode has **no login**, so it binds `127.0.0.1` and is reachable only from the machine running Condor.
If you need it from elsewhere, put something that authenticates in front of it rather than setting `WEB_HOST=0.0.0.0` on its own:
* **Tailscale** — re-run `make setup` and enable it. Condor then binds loopback and lets `tailscale serve` expose the dashboard to your tailnet only.
* **SSH tunnel** — `ssh -L 8088:localhost:8088 you@host`, then open `http://localhost:8088` locally.
* **Switch to Telegram mode** — re-run `make setup`; `/web` then issues time-limited login links that work from any device.
### Docker, updates, and data
1. **Docker daemon:** The deploy script checks that Docker is running before bringing up the API. On Linux: `docker info`. On Mac/Windows: open **Docker Desktop** and wait until it is fully started.
2. **Compose:** You need either `docker compose` (plugin) or legacy `docker-compose` (the installer checks this).
3. **API-only recovery:** If Quick Start skipped or failed the API step, use the **Hummingbot API only** tab command, or from `hummingbot-api`: `make setup`, `docker compose pull`, `make deploy` (see [hummingbot-api](https://github.com/hummingbot/hummingbot-api) README).
4. **Sibling layout:** Condor's setup wizard expects **`hummingbot-api`** next to **`condor`** (`../hummingbot-api` from the Condor directory) when both are installed by the same flow — keep that layout unless you know how to point `config.yml` at a custom URL.
5. **API errors mentioning `DockerService` / `'DockerService' object has no attribute 'client'`:** Docker (or its daemon) wasn't running when the `hummingbot-api` container itself started, so it never connected. Start Docker, then restart or redeploy the `hummingbot-api` container so it reconnects — restarting Docker alone isn't enough once the API is already up.
`make run` rebuilds the dashboard before starting, but it only installs frontend packages when `frontend/node_modules` is missing **entirely**. After a `git pull` or `/update` that added a new frontend dependency, the stale `node_modules` fails the build with an error naming the missing package.
```bash theme={null}
cd frontend && npm install
cd .. && make run
```
`make doctor` warns when `node_modules` is absent, but cannot tell a stale one from a fresh one — a build error naming a package you never heard of is this case.
Condor's dashboard preferences, chat state, and agent conversations persist to a pickle file (`data/condor_bot_data.pickle`) with a `.bak` backup. If the main file is corrupted, Condor recovers from `.bak` automatically; if both are corrupted (for example after a hard crash or a full disk), it silently starts with empty state instead of failing to boot — the only trace is a warning in the logs, not an error you'd notice at the time.
There's no way to recover state once both copies are gone. If this happens repeatedly, check for disk space issues or anything killing Condor mid-write.
## Secure the message broker
Condor and Hummingbot API reach bot instances through an **EMQX** broker. Older Hummingbot API installs ran this broker with no authentication and published its port on every interface — if you installed before the fix, or haven't redeployed since, treat it as exposed until `make emqx-audit` says otherwise.
See [Broker Security](https://hummingbot.org/hummingbot-api/broker-security/) in the Hummingbot API docs for the full issue and the fix (`make deploy`, `make emqx-auth-reset`, then `make doctor` / `make emqx-audit` to verify).
A few things worth knowing beyond that fix:
* **Rotating `BROKER_PASSWORD` later** needs `make emqx-auth-reset` too, not just `make deploy` — EMQX only imports the bootstrap file for accounts that don't already exist, so a broker that's already running keeps the old password until its data volume is reset.
* **Restarting a bot instance doesn't refresh its broker credentials** — only (re)creating one writes the current password into its `conf_client.yml`. After any broker credential change, recreate existing instances rather than just restarting them.
* **Bring the stack up with `make deploy`, not a bare `docker compose up`** — the plain compose command skips the step that creates the broker's credential file, so the broker comes up "healthy" with zero accounts and rejects everyone, including the API itself.
* **Default credentials aren't a hard failure** — `hummingbot-api` boots fine on out-of-the-box `USERNAME`/`PASSWORD`/`CONFIG_PASSWORD` values and only logs a warning. Change them before this instance touches real funds.
## Recovery toolkit
The commands worth reaching for before reading anything above. All are safe to run at any time; none of them trade.
| Command | Where | What it tells you |
| ------------------------------------------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `make doctor` | Condor dir | Dependencies, `.env`/`config.yml`, AI model, dashboard bind, Tailscale, and whether each API server is reachable **and** authenticating |
| `curl -s -o /dev/null -w "%{http_code}" localhost:8000/docs` | API host | Whether the API answers at all — **200** means up |
| `make status` | Condor dir | Whether Condor is running, and under which tmux session |
| `make logs` | Condor dir | Attach to the running session (detach with Ctrl+B then D) |
| `make restart` | Condor dir | Rebuild the frontend and restart — the fix for a stale dashboard |
| `tailscale status` | Either host | Whether this machine is on the tailnet at all |
| `tailscale serve status` | Condor host | What is actually published to the tailnet, including the dashboard |
| `docker compose ps` | `hummingbot-api` dir | Whether the API, broker and database containers are up |
| `make emqx-audit` | `hummingbot-api` dir | Broker listeners, auth, ACL and any rule-engine rules |
If `make doctor` is clean and something is still wrong, that is worth reporting — it means a real gap in what the check covers.