Skip to main content
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:
    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. If you must use a public IP instead, allow inbound 8000 only from the Condor host. See also: Hummingbot API Tailscale guide

​
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, and ADMIN_USER_ID must be your numeric Telegram user id (from @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 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.
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 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. If make doctor is clean and something is still wrong, that is worth reporting — it means a real gap in what the check covers.