Troubleshooting

The doctor

candle-harness doctor

The doctor checks your whole setup and says exactly what to fix. Each line is ok, warn, FAIL or skip, with the area it checks, and under anything that isn’t ok, an arrow and the fix:

FAIL  key     agent-b has no key file (…/state/keys/agent-b.key)
              → Run `candle-harness key add --agent agent-b` with its key.

Fix the first FAIL, then run it again. It ends with “All checks passed”, “Nothing blocking”, or how many problems are left, and then, under To look at, every line that isn’t ok once more, failures first, so they aren’t lost among the lines that passed.

It checks:

Area	What it checks
paths, config, state	Where the Candle Harness keeps its files, config.toml, that the state folder is private, entries in your PATH that aren’t full paths (left out of what the Candle Harness runs), and a warning when it runs as root on Linux
setup	Where setup stands, if it hasn’t finished
key, access	Each agent’s key file, and each key’s access as Candle lists it, naming any with Withdraw access
candle	The candle CLI’s version, the profile the Candle Harness acts as and whether it’s signed in, each agent through Candle’s own server, and the RPC a TEE wallet’s trades use
engine, claude	Every coding agent you have: its version (a warning on a newer major version than the one its holds were checked on), what it can’t do here, its models and sign-in, and a one-word test turn on each engine an agent is on
wallet	Each wallet: who pays from it, its approvals setting, TEE wallets’ signers, stranded wallets, empty token accounts
limits	Each key’s Candle cap and how much is used, keys Candle doesn’t cap, and any key Candle is holding now
vault	Whether this machine has a vault
hacc	Whether Hacc takes each key, the account’s plan, and the signal stream
tools, skills, memory	Each agent’s shell and hidden tools, its skills, and its memory
pnl, journal, away	The P&L window and samples, the Journal’s size, and the last gap While you were away covered
layouts, theme, aliases	Problems in your files, each named with its line
core	Whether a core is running and what holds it up, a core still on an older version after an update, the login service and lingering, and keep-awake on a Mac
trigger	Each trigger that’s on and what it watches, a level checked slower than it should be, one held and why, and problems in triggers.toml
bot	Each rules bot: paper or live, what it does now, its wallet and open positions; one held and why, one Candle’s stop paused, a sell held after two failed sells, a live bot on a shared wallet, and problems in bots.toml. Each code bot: what it does now, its process (running, crashed, given up after five crashes), its folder missing, a bot run outside with no token or not connected, a memory or CPU warning, and the exits the core holds for it
build	Your bots folder (not opened yet, missing, files missing or from an older Candle Harness, and the ones you changed, kept), each coding harness the Build tab can open with its version, and the one it opens
notify	What reaches you while the Candle Harness’s window isn’t in front, and with no window open
debug	A debug switch that’s on

candle-harness doctor --offline skips everything that reaches the network or costs a turn: Candle, the engines’ model lists and their test turns.

A test turn spends your model credit, so the doctor sends one only to engines an agent is on.

Installing

Installing covers the snags at install time:

• macOS saying it can’t verify a downloaded file;
• candle or candle-harness not found after installing;
• every command saying “command not found” after a PATH line went wrong;
• Linux with no keychain;
• a new Candle account that can’t make a key yet;
• a coding agent that isn’t installed.

Setup

“Not approved in your browser” / OWNER_CONFIRM_DENIED or OWNER_CONFIRM_EXPIRED. Candle asked for the owner’s approval in the browser, and it was denied, or the code’s 5 minutes ran out. Nothing changed and no key was made. Make the key again, open the link the pane shows (signed in as the account’s owner), check the code matches, and approve.

403 OWNER_CONFIRM_REQUIRED on an owner step. Your candle is older than 0.13.20 and can’t wait for the browser approval. Run candle update, then try again. candle-harness doctor names the version.

Setup stopped partway. Run candle-harness again: it picks up where you stopped, and never runs a step twice. A key that was made but not stored is offered for revoking first.

“Candle won’t make a key yet.” A new Candle account must authorize its embedded wallet for agents once, on Candle’s site. Open the Agent Console that setup links, make a key there with Create key and authorize, and approve what Candle asks. Then Try again in setup.

The coding agent isn’t signed in. Setup’s engine step signs it in, in a pane. Or sign in with the agent itself (/login in Claude Code, for example), then pick it again.

On Linux: “No keychain available”. The Candle CLI keeps its sign-in in an encrypted file there, locked by a passphrase in CANDLE_KEYRING_PASSPHRASE. Setup shows the export line to paste into your shell’s start-up file in an editor (not typed at a prompt), and chmod 600 for that file. Add it, quit, open a new terminal, and run candle-harness again. Or keep the owner sign-in off this machine and add an agent’s key made elsewhere with candle-harness key add --agent <name>. This isn’t a vault’s passphrase (Installing).

On Windows. Use WSL 2 and the Linux bundle, from your Linux home. The installer skips a Windows candle under /mnt/.

Trading

A trade was refused. The refusal says why, with the figures: over a limit, paused by the kill switch, a key Candle is holding, or a wallet the agent can’t pay from. Limits says what each of Candle’s refusals means.

“Holds no …” straight after a buy. Candle’s portfolio can take a moment to show a fill. Wait a few seconds and sell again.

A trade Candle didn’t answer. It waits in the agent pane. resend, from the main window, reads it back from Candle first, so it’s never sent twice; abandon lets it go.

An expired card says “ask for it again”. A card made from something that may have changed since (a trigger, a bot, approvals, a Hacc change) is never re-quoted. Ask for it again.

”… is what trades spend”. SOL, USDC, ETH and USDG can’t be bought or sold as a trade’s token, on paper either. Convert one with a swap.

A typed trade went nowhere. A line shaped like a trade that can’t run says why and keeps the line, rather than sending it to the agent. A token named only by a name nobody has shown this session isn’t guessed: give its mint, or ctrl-t to ask the agent.

Panes say “every 10 s (Candle’s limit)”. Background reads are slowing down to stay inside your key’s requests a minute. Trades never wait for them. On Free’s 30 a minute, a second agent adds a key’s worth of room.

The agent

It answers “not signed in”, or the turn ends with a sign-in error. The engine’s sign-in has expired. Sign in again with that coding agent, or through ctrl-g, which says what to do.

A rate-limited Codex. Codex can wait minutes on its provider’s rate limit. The Candle Harness reads its retry line, ends the turn with words, and says so.

A Grok turn ended on a command. With a shell list, Grok ends the turn on a command that isn’t on it, naming the command. Ask again without it. Engines has Grok’s rules.

It can’t read a file you gave it. The agent reads only its own research folder, research/<agent>/ beside config.toml. Put the file there.

Its memory has gone stale. Open the palette’s memory row, and delete lines or clear it.

Triggers

A trigger didn’t fire. Open the Triggers overlay: it says whether the trigger is on, what it’s checking and how often, when it last fired, and anything holding it (the kill switch, your plan, an edit by hand, a cooldown), or that it isn’t watching now and why. A trigger fires in the mode you approved it in, paper or live, whatever the Candle Harness’s mode. A trigger needs a core running: with the Candle Harness closed, one that’s on keeps it up, and after a restart candle-harness service install starts it at login. candle-harness doctor says when triggers are on and no core is watching them.

A stop sold below its level. A level is checked about every 5 seconds, and the sell fills at the price then. A fast move can pass through the level first.

A trigger’s card expired. It asks you each time, and nobody pressed it within 60 seconds. ctrl-r in the Triggers overlay proposes it again at a fresh price. To have it run on its own, pay from a wallet that trades inside limits (Triggers).

A wake was skipped. The agent was woken as often as its caps allow: 4 an hour and 24 a day unless [agents.<name>.wake] says otherwise.

No notifications. candle-harness doctor’s notify lines say what this machine can send. Over SSH, a notification needs a view open and a terminal that shows them; otherwise the bell rings.

Rules bots

A bot didn’t buy. The Bots tab counts what it skipped over the last day, by why: no free slot, a token Candle couldn’t price yet, its market cap, Hacc’s filters, the wallet’s balance, Candle’s pace. A bot acts only on signals from after it was switched on, and only while a core runs. A buy over the wallet’s figures, or from a wallet that asks every time, is a card that’s skipped if nobody presses it within 60 seconds.

A bot’s sell is held. Two sells of that token failed on the key, and a third would stop the key on Candle. Check why (on a young token, often slippage: ask the agent for a looser bound for the bot), then use its retry its sells chip.

A bot is paused and you didn’t pause it. Its agent paused it, the kill switch’s report names it, or Candle stopped its key: the Bots tab says which. For Candle’s stop, resume the key in Candle’s Agent Console first, then put the bot back on.

A bot sold less than it bought. On the embedded wallet, for a token Candle didn’t launch, a bot sells a whole percent of the wallet’s balance, rounded down, so a little can stay. If you or the agent sold some of it, the bot says how much was sold outside it. A wallet of its own avoids both (Rules bots).

Code bots and the Build tab

A code bot isn’t running. Its row on the Bots tab says why first: crashed and starting again, crashed too often, its process stopped, not running, or run outside and not connected. candle-harness bots logs <name> shows the end of its log, its own errors and the core’s lines among them. Once fixed, start it on the Bots tab, or candle-harness bots start <name>, runs it again.

It stopped trying after five crashes. Five crashes in ten minutes, including a start that couldn’t happen (no folder, a program that isn’t installed). It stays stopped until you start it, across a restart too. Read its log, fix the code or the command, then start it.

Its buy was refused. The refusal names which figure: a trade’s, a day’s, or open at most. Those are its card’s; ask your Build tab’s harness to propose new figures, or the agent to lower them. A buy also waits as a card on a wallet that asks every time, and is refused while the bot is paused, held by your plan or an edit of bots.toml by hand, or while the kill switch is on.

A bot you run yourself can’t connect. Run candle-harness bots token <name>, which writes its token and the socket to .harness-bot.json in its folder, and start it from that folder. A token stops working once the core issues another (each bots start or bots token does), once its process here is stopped, and once the bot is removed. Approving a new folder or command for it withdraws its token too: run bots token again. A core must be running.

Your harness won’t start in the Build tab. The pane’s harness ▾ picks another, and “another command…” takes any program. candle-harness doctor lists each harness the Build tab can open and its version. To sign in over SSH, see The Build tab.

build test or build propose is refused. They need Pro or Max, and a Build tab open in the Candle Harness: the commands use that pane’s own token, so they don’t work from another terminal.

A daemon is still running after the harness quit. The bots folder pane lists it with a stop chip.

The bots folder has a file you changed, and the Candle Harness kept it. That’s on purpose: it never writes over your changes. To take its newest copy, delete the file and run candle-harness bots init.

The status bar says “the core is still …”. You updated while a core was running, and it carries on as the older version. Its restart it chip stops it and starts the new one, the login service’s when it’s installed. From a shell: candle-harness stop, then candle-harness (or candle-harness service install with the login service, so the new core outlives the window).

The code runner refuses a runtime. A python3, bun or node installed straight in your home folder, ~/.config or the Candle Harness’s own folder is refused, since a script could then read those. Install it in a folder of its own.

The code runner isn’t offered. It’s off until you turn it on for an agent (ctrl-g’s code runner row). Where the row says it can’t be held here, that’s Linux before 6.12 or Landlock turned off; the doctor’s tools lines say which. A script that can’t find a package installed in your home folder can’t read it: install it for the runtime itself (Your agent).

The screen

Copying text. Select it with the mouse, then ctrl-c. For an address, use its ⧉, which copies it in full.

A pane says it couldn’t read. It says why, in words. The doctor usually says more.

The status bar says “the core stopped · reconnecting…”. The core went away while the window was open, and the window tries to attach again. If you installed the login service, it starts the core again by itself; otherwise quit and run candle-harness, which starts it. Nothing is sent twice: a trade that was under way is read back by its id.

Pop-out shows a command rather than a split. Outside tmux or cmux, the Candle Harness can’t open a split itself. Paste the command it shows into a new terminal window.

The Terminal theme doesn’t change anything. Your terminal didn’t say what its colours are within a second, so the theme you had stays. Try Candle dark or Candle light, or a theme of your own.

A file you edited isn’t taking. layouts.toml, wallets.toml, a theme or an alias with a problem is named with its line, on screen and by the doctor, and the rest of the file is used. A file with a problem is never written over.

The debug switch

CANDLE_HARNESS_DEBUG_LOSE_NEXT_REPLY makes the core drop Candle’s next answer, to test how a lost answer is read back. When it’s set, the doctor, the status bar and the Journal say so. Unless you’re testing that, unset it.

Still stuck

Open an issue at candledottv/harness, with the doctor’s output. It never prints a key. For a security issue, email security@candle.tv instead.