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 Workspace.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 Workspace, :8000 for the API).To move the Workspace instead, change the port in WEB_URL in Condor’s .env. WEB_URL sets the port Condor listens on and wins over WEB_PORT, so changing only WEB_PORT does nothing when WEB_URL is set. A WEB_URL with no port makes Condor listen on 80 (http://) or 443 (https://), which often collides with a web server. The API’s port 8000 is fixed in hummingbot-api’s docker-compose.yml; API_BIND changes the address, not the port.

​
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 approves you with /admin in Telegram or Settings → Admin in the Workspace.
  4. Another bot’s token: If the log shows a warning that TELEGRAM_TOKEN is set in the environment Condor was started from and overrides .env, Condor is running as a different bot. This often happens inside a tmux server started from another project. Unset it (unset TELEGRAM_TOKEN, or tmux set-environment -gu TELEGRAM_TOKEN) and restart. See Environment overrides.
  5. 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.Tailscale does not change this: Local mode stays on 127.0.0.1 even with Tailscale on. Don’t set WEB_HOST=0.0.0.0 to work around it. Instead:
  • 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. With Tailscale on, the Workspace is reachable at http://<tailnet-ip>:8088 from your tailnet.

​
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 and make restart rebuild the Workspace before starting. They reinstall the frontend packages with npm ci first whenever frontend/package-lock.json is newer than what is installed, so a pull that adds a dependency is picked up on its own.If the build still fails, the error is printed before Condor starts. Read it in the terminal where you ran the command. To retry the install by hand:
Condor keeps these in different places:
  • Preferences and server settings: config.yml.
  • Agent conversations: .condor/users/<user-id>/conversations/.
  • Telegram session state: data/condor_bot_data.pickle, with a .bak copy.
The most common cause is a changed user id. Everything is keyed to the id you log in as, so a Local install (user 1) that switches to Telegram starts with an empty history under your Telegram id. The old conversations are still under .condor/users/1/. See Add Telegram to a Local install.If the pickle file is unreadable, Condor recovers from .bak. If both are unreadable, it starts with empty Telegram session state and logs the error Both pickle and backup are corrupt/unreadable. Starting with empty state. This doesn’t affect conversations or config.yml. If it happens repeatedly, check for a full disk 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.