Troubleshooting

Almost every report here is one of six things, and four of them produce no error message at all — Hummingbot swallows connector import failures and balance-fetch failures by design. Start with the four commands at the bottom of this page before assuming anything.

connect does not list bicrypto

Hummingbot discovers connectors by importing them. Its discovery scans its connector folders and imports each <name>_utils inside a bare except ModuleNotFoundError: continue, so a connector that is absent or unimportable is silently skipped. There is nothing in the log to read.

The installer also detects directories readable but not enterable, case-variant folder names, leftover files from older versions, locally modified files, and being pointed one level too deep or too shallow.

Not a cause: a missing __init__.py. Python namespace packages import a directory fine without one.

create does not list bicrypto_pmm

Expected, and reinstalling will not change it. create is the Strategy V1 wizard and only ever offers V1 strategies. bicrypto_pmm is a V2 controller — a separate system create never lists.

Start a controller through a script config that names it, then start --v2 my-strategy.yml. The --v2 flag resolves against conf/scripts/, not conf/controllers/; passing the controller filename produces V2 config file not found. See Connecting a bot.

balance is empty, with no error

Hummingbot renders a failed balance fetch as an empty list rather than a message. Most common causes first:

Signature, clock and scope rejections

A clock rejection is recorded against the key, so it appears in that key's audit trail on the admin side. That is deliberate: drift used to leave no trace on the exchange at all, which sent people off to reinstall a connector that was fine.

SSL: "unable to get local issuer certificate"

A server certificate problem, not a connector one. Your web server is serving only the leaf certificate without its intermediate — browsers paper over that and Python does not.

openssl s_client -connect your-domain.com:443 -servername your-domain.com < /dev/null

unable to verify the first certificate confirms an incomplete chain. Serve the full chain — with Let's Encrypt use fullchain.pem, not cert.pem.

"Bid/Ask orderbook is empty"

The strategy has no prices to quote against. Check in order:

Orders and fills

Placed in Hummingbot, never appears on the exchange. Check the kill switch and read-only mode first — both reject placement. Then the balance in the relevant wallet, and that the size clears the market's minimum notional.

Filled on the exchange, Hummingbot never notices. Fills reach bots through the WebSocket stream. Confirm the socket is connected and check the fill-detection poll interval in Settings. Hummingbot also polls order status as a fallback, so a persistent miss on both paths points at the WebSocket connection itself.

Every order is a fraction of the size asked for, on perpetuals. Fixed. An older connector divided leveraged quantities by the leverage factor, so 1 contract at 20× opened 0.05 — and the response echoed the shrunken size back, so Hummingbot's own reconciliation agreed and never raised a discrepancy. Reinstall the kit.

XEMM is not hedging

Almost always a profitability target set below the fee-and-slippage floor, so no level ever qualifies. Recompute it against your own fee schedule — see Strategies. Also confirm the taker venue's own credentials are connected inside Hummingbot: connecting bicrypto does nothing for the hedge leg.

Server-side instances

An instance goes straight to Crashed. Press Diagnose. The reason will be one of the failed checks with the fix beside it; the most common is a Python interpreter that cannot import the checkout, which means the wrong conda environment. The card also names a probable cause from the exit itself rather than showing "exited with code 1".

"Config password can no longer be decrypted." APP_ACCESS_TOKEN_SECRET was rotated, which invalidates stored passwords by design. Edit the instance and re-enter the Hummingbot config password.

The bot starts, stays alive, and never quotes. Its market is not one the exchange lists — the connector subscribes and waits forever for a book that never arrives. Registering and starting now refuse this and list the pairs that do exist, but an install without the Ecosystem addon cannot read the market list, so the check yields nothing and the start is allowed.

An instance is killed repeatedly. Look for a memory-limit line in the logs. XEMM runs two connectors and needs roughly twice the memory of a single-pair market maker. Raise the cap if the host has headroom, and reconsider running it there at all if it does not.

Config changes appear to do nothing. Configuration is read at launch, so a running process keeps what it started with. Press Restart — that regenerates the controller YAML from the preset and relaunches.

Bots do not come back after a deploy. Check the backend log for [HB] Hummingbot supervisor not started. The supervisor runs on the main thread only, and its failure is deliberately non-fatal so the exchange still boots.

The whole Hummingbot admin section is empty for everyone but the owner

The section root gates on access.hb. Super Admin bypasses permission checks entirely, so an install where nobody else can open it looks fine from the owner account. Grant the section and the four view-level keys in Admin → Roles — they are listed on Install and enable.

If the section is missing entirely for everyone, check the licence: /api/hb and /api/admin/hb are both licence-enforced prefixes, so an expired or unverified licence removes the whole surface rather than one screen.

Before opening a support ticket

These four commands answer most questions before they need asking.

# 1. Is the server side alive?
curl https://your-domain.com/api/hb/ping

# 2. Is its clock sane? Compare with your own.
curl https://your-domain.com/api/hb/time

# 3. Does the pair you want to quote exist, and does it read TRADING?
curl https://your-domain.com/api/hb/exchange-info

# 4. Is the connector install healthy?
python install_connectors.py /path/to/hummingbot --doctor

Include the output of all four, plus the last 200 lines of the Hummingbot log, when you report a problem. For a server-run instance, include the Diagnose result and the tail of the instance log instead of the fourth command.