Troubleshooting

Find the message you got, or the thing you saw, and what to do about it. Paste the message into the box to see only the entries that match, or scan the groups below: they are in the order you meet them, from starting a flow to writing one.

Every entry says the same four things: the symptom you see, its cause, the fix, and how to verify that the fix worked. A message quoted here with … or a name such as build-box matches yours with your own names in those places.

⌕

Try

Filters this page as you type. Nothing you paste leaves your browser.

Starting a flow

hmz exec prints these after hmz exec: error: and exits with status 2. Nothing has run. At the prompt, the same words follow hmz:. Every one of them is checked before the first turn, so trying a line by hand takes a second: see Run it unattended.

rlar needs an agent for 'actor', 'reviewer'; specify each with -a ROLE=CLI/MODEL:EFFORT

Symptom. hmz exec refuses the line, naming the roles left empty.

Cause. The flow has agent roles that nothing on the line fills.

Fix. Give one -a per role, named after the role:

hmz exec -f rlar -a actor=claude/claude-opus-5:high -a reviewer=codex/gpt-5.6-sol:high \
    -p budget.cost=20 "fix the build"

Verify. The line gets past the check and the first agent starts working.

ralph_loop has no agent role 'builder'; available roles are 'agent'

Symptom. hmz exec refuses an -a, and lists the roles the flow does have.

Cause. The line names a role the flow does not have: a typo, or another flow's role.

Fix. Use a name from the list at the end of the message. chat has assistant, ralph_loop has agent, and rlar has actor and reviewer. Each flow's page lists its roles.

Verify. The line is refused for nothing, or for the next thing it is missing.

…: 'human' is assigned automatically by the runtime and cannot be set with -a

Symptom. hmz exec refuses an -a for a role such as human.

Cause. That role is the person outside the run, and Humanize fills it. … is the workspace the run started in and cannot be set with -e is the same for an environment: it is the directory you ran hmz exec in.

Fix. Take the role off the line. For the workspace, run hmz exec from the directory you want the agents to work in.

Verify. The line runs without it.

-a 'claude/claude-opus-5:high': expected <role>=<harness>[@<provider>]/<model>[:<effort>]

Symptom. hmz exec prints its usage, then this.

Cause. The agent has no role in front of it.

Fix. Say which role it fills: -a agent=claude/claude-opus-5:high.

Verify. The usage line is gone.

-a 'agent=claude:high': expected [NAME=]CLI[@PROVIDER]/MODEL[:EFFORT]

Symptom. hmz exec prints its usage, then this.

Cause. A part is missing, or the CLI is not one Humanize knows. The CLI and the model are required; the effort may be left off, which asks for none.

Fix. Write the CLI, a / and the model, and the effort after a : if you want one. auto is the effort that asks for none:

-a agent=claude/claude-opus-5:high
-a agent=opencode/anthropic/claude-opus-5:auto   # a model may hold slashes

Verify. The usage line is gone. Try a spec in the reader on Run it unattended to see how it is read.

ralph_loop requires a budget: specify with -p budget.cost=...,budget.duration=...,budget.output_tokens=...

Symptom. hmz exec refuses the line before anything runs.

Cause. Every flow except chat runs under a budget, and the line gives none.

Fix. Give it one with -p budget.<limit>=:

-p budget.cost=20
-p budget.duration=6h,budget.output_tokens=10m

See Every run has a budget for what each key stops.

Verify. The run starts. When it later reaches a limit, it ends with hmz exec: stopped -- … and exit status 0.

agent=claude/claude-opus-5:ultra: claude cannot be asked to think at 'ultra'; expected one of ultracode, max, xhigh, high, medium, low

Symptom. hmz exec refuses the agent, and lists the efforts its CLI takes.

Cause. That effort is not on the backend's ladder.

Fix. Pick one from the list, or auto for none. A CLI you added on the Accounts page of /settings takes any effort. Every ladder is on Efforts.

Verify. The line gets past the check.

cursor-agent lists no gpt-5.2-medium: this account runs gpt-5.2 as gpt-5.2-low, gpt-5.2-high

Symptom. A Cursor Agent role is refused, with the ids this account offers.

Cause. cursor-agent writes the effort into the model's id, and this account does not offer the model at that effort.

Fix. Pick an effort the message lists: here gpt-5.2:low or gpt-5.2:high.

Verify. The line gets past the check.

…: 'reviewer' needs GoalCommandAgentMixin, which pi does not support

Symptom. hmz exec refuses a CLI for one role.

Cause. The role asks for something that CLI cannot do: pursue a goal, be steered, or answer a hook.

Fix. Give the role a CLI that can. Reference › Flows has the table of which CLI does what, and the agent sheet at /flow offers only the CLIs that can.

Verify. The line gets past the check.

…: 'builder' requires claude, but got codex

Symptom. hmz exec refuses a CLI for one role, naming the one it wants.

Cause. The role is written for one CLI only.

Fix. Give it that CLI.

Verify. The line gets past the check.

nosuchflow: no flow is called 'nosuchflow'

Symptom. hmz exec cannot find the flow -f names.

Cause. Nothing offers a flow by that name. A bare name is looked up in this project's .hmz/flows, then in ~/.hmz/flows, then among the flows built into Humanize and those installed from a flowverse. Only what starts with ., / or ~ is read as a path.

Fix. Check the spelling against the names /flow offers, or give the flow's path with its ./, or its repository as git+https://…#<subdir>.

Verify. The line is refused for nothing, or for what the flow itself needs.

local/twice: a flow of local is called @local/twice now

Symptom. A name that used to work is refused, saying how it is said now.

Cause. The flows of every place but official are named after an @: @local/twice, @user/twice, @<flowverse>/<flow>. alice/kernel is now a flow the official flowverse lists under the GitHub user alice, and a relative path needs its ./ (flows/twice: a path starts with ./, / or ~, as ./flows/twice does).

Fix. Say it as the message does. What /flow remembered under the old name is not carried over: set the flow up again under its new one.

Verify. The line is refused for nothing, or for what the flow itself needs.

flame_chasoid:parallel_git_pr: not installed -- install it from /flow (flowverse official)

Symptom. hmz exec refuses a flow by name that a flowverse lists.

Cause. A flow a flowverse lists runs only once it is installed, and hmz exec installs nothing. Only the flows built into Humanize are there from the start.

Fix. Install it: type /flow, press Install more…, open the flowverse the message names, and install the flow. From a script, or on a machine that never opens hmz, such as a CI runner:

python -c 'from hmz.sdk import Hmz; v = Hmz().verses; v.fetch("official"); v.install("flame_chasoid")'

Or name a release by its repository, which runs it without installing anything:

-f 'git+https://github.com/humanfia/flame-chasoid-flows@v0.1.0#flame_chasoid:parallel_git_pr'

Verify. /flow lists the flow, with its version at the end of its row, and the line gets past the check.

flame_chasoid:parallel_git_pr: the official flowverse has not been fetched yet -- fetch it from /flow

Symptom. hmz exec refuses a flow by name, on a machine that has not fetched the official flowverse. Until it is fetched, any name that nothing else offers gets this message, even one that is misspelled. The flows Humanize ships, such as chat and ralph_loop, never do.

Cause. The flowverse's index has not been downloaded yet. hmz fetches every flowverse in the background each time it starts, and hmz exec never does.

Fix. Open hmz once and let it fetch, or fetch now: type /flow, press ←, open Flowverses, and press Fetch with the cursor on official. Then install the flow, as above.

Verify. The flowverse's card says fetched, and the line gets past the check, or says the flow is not installed.

… holds gen-idea, gen-plan, rlcr and none is called 'humanize1'; name one as humanize1:<flow>

Symptom. -f names a directory of flows, and hmz exec asks which one.

Cause. The directory holds several flows, and none is named after it.

Fix. Say which one you mean: -f humanize1:gen-plan. A name that is not among them gets … holds no flow called '…'; it holds …, with the list to choose from.

Verify. The line gets past the check.

…: 1 validation error for Params

Symptom. hmz exec refuses the -p, with the lines after it naming the key:

hmz exec: error: chat:chat: 1 validation error for Params
foo
  Extra inputs are not permitted [type=extra_forbidden, input_value=1, input_type=int]

Cause. -p gave a key the flow does not take, or a value its type cannot read.

Fix. Fix the value, or leave the key off to get its default. The flow's page lists its params.

Verify. The line gets past the check.

hmz exec: error: unrecognized arguments: -H …

Symptom. hmz exec prints its usage, then this.

Cause. hmz exec takes no -H: where each agent's CLI runs is not said on the line. It is the harness setting of the runtime the work is on, saved with the host or the daemon.

Fix. Drop -H. For -H local, save the host or daemon with local in its harness runs on row on the runtimes page; for -H env, with env (or blank, the default); for -H standalone:…, with that other saved runtime, as ssh:gpu-box. See Where the agent runs.

Verify. The usage line is gone.

build-box: 'somewhere' is not where a harness runs: env, local or <ssh|docker|swarm|apple-container|slurm>:<runtime name>

Symptom. Saving a host or a daemon on the runtimes page, or Hmz().runtimes.new(…), is refused with this, or with … its harness names itself; env is its own machine.

Cause. Its harness, the harness runs on row, is none of env, local and <backend>:<name>, or names the runtime itself. It holds one place, not a list.

Fix. Write one of those, as env, local or docker:gpubox. For the runtime itself, write env.

Verify. It saves.

stateful_ralph has no run to resume here: none saved any progress

Symptom. A --resume line is refused.

Cause. --resume found no run of this flow in this directory that saved anything to pick up from. The runs are kept on the machine that ran them, so a fresh CI runner never has one. … does not support resuming, so there is no run to resume means the flow cannot be resumed at all.

Fix. Run the line without --resume, from the directory the earlier run started in if there was one. See Picking a run up.

Verify. /epics in that directory lists the run as resumable.

hmz exec: nobody lists a price for my-model, so cost=5 cannot stop what it spends

Symptom. A warning before the first turn. The run goes ahead.

Cause. Humanize knows no price for that model, so a cost cap never fills. It happens for a model the price list does not have, and for every model on a machine that has never opened hmz, which is what fetches the list.

Fix. Cap something it can count as well:

-p budget.cost=5,budget.output_tokens=2m

Verify. The warning is still printed, but the run now stops at the other limit, with hmz exec: stopped -- … its budget's output tokens are spent.

hmz exec: error: the price list … at nan dollars, which is not a number

Symptom. hmz exec exits with status 2 before the first turn, and the interface refuses the run with the same words.

Cause. The price list gives some model a price that is not a number (NaN, an infinity, or one too large to be a number). One such figure would make every cost limit of the run unenforceable, so no run starts on it. Either the list being fetched is malformed (the words say the price list at <source>), or the copy kept on this machine is (the price list kept at <path>).

Fix. Point HUMANIZE_PRICES at a list whose prices are numbers, or set it to off. For the kept copy, delete the file the error names.

Verify. The run starts. With HUMANIZE_PRICES=off and no copy kept, every model is unpriced, and a cost limit warns as above.

the following arguments are required: task

Symptom. hmz exec prints its usage, then this, although the line has a task.

Cause. The task starts with a dash, so it was read as a flag.

Fix. Put -- before it:

hmz exec -f chat -a assistant=claude/claude-opus-5:high -- "--force is not a flag here"

Verify. The run starts.

At the prompt

The interface prints most of these in red, after hmz:.

no coding agent is installed

Symptom. You typed a task, and nothing started.

Cause. The flow has no agent to run it on. Humanize looks for a coding agent CLI on your PATH and in the directories installers use, such as ~/.local/bin and /usr/local/bin, and found none.

Fix. Check what it can find:

command -v agy claude codex cursor-agent grok kimi mcode mimo omp opencode pi qwen

Install one from Installation, then open hmz again. If one is installed, open /flow and give the role a CLI and a model.

Verify. command -v prints a path, and the task starts a turn.

no such flow: ralph

Symptom. A $ line is refused.

Cause. A $ line names a flow by the name it is offered under:

Flow	Typed as
built into Humanize, or installed from the official flowverse	$ralph_loop
this project's, in .hmz/flows	$@local/twice
yours, in ~/.hmz/flows	$@user/twice
installed from another flowverse	$@<flowverse>/name

Fix. Type $ and let completion offer the names. A flow a flowverse lists is offered only once it is installed: type /flow and press Install more….

Verify. The flow's /flow sheet opens, or it starts.

no such command: /foo

Symptom. A / line is refused.

Cause. There is no command by that name. There are ten, listed in Reference › TUI.

Fix. Type / alone: the list above the prompt shows the commands that would do something now.

Verify. The command runs.

no flow is running, the flow is already stopping

Symptom. A /stop did nothing but say this.

Cause. There was nothing to stop. /stop is listed only while a flow runs and has not already been told to stop; typed out otherwise, it says why it did nothing. The same goes for every command the list leaves out: /resume with a flow going or nothing here to carry on, /btw with nobody to ask.

Fix. Nothing to do. Wait for a flow that is stopping to finish its turn.

Verify. The status line no longer shows the flow running.

cannot choose a flow while one is running

Symptom. A /flow <name> or a $ line is refused while a flow runs. a flow is already running has the same cause.

Cause. Starting another flow would stop this one, so Humanize refuses.

Fix. Stop it first with /stop, or ctrl+c twice on an empty line. /flow on its own still opens, on the roles of the flow that is running.

Verify. Once the run has stopped, the same line opens or starts the flow.

reviewer is not configured yet

Symptom. /flow will not save.

Cause. The role has no CLI and model yet. this flow requires a budget: set the budget first is the same for the budget.

Fix. Open the role's row, choose a CLI and a model, and save the agent. For the budget, open the budget row and set at least one limit.

Verify. Save closes the agent's sheet, and the role's row shows what fills it.

flow not set up; nothing started

Symptom. A $ line opened /flow, and when you left it nothing ran.

Cause. The flow has never been set up in this directory, and you left the sheet without saving.

Fix. Type the line again, fill every role, and press Save this time.

Verify. The flow starts on the task.

expected 'on' or 'off', not 'yes'

Symptom. An /afk or a /claim with a word after it is refused.

Cause. Given nothing, they switch over. Given a word, they take only on or off.

Fix. Type /afk, /afk on or /afk off.

Verify. The status line starts with afk while you are away, and does not once you are back.

reviewer is bob@tui's to answer, not yours

Symptom. A line typed on an outworlder's transcript is refused.

Cause. Another interface reading the same run, or a program on the SDK, has claimed that outworlder: what it asks is theirs alone to answer. reviewer is bob@tui's says the same about an answer, and reviewer is bob@tui's: cannot claim it or …: cannot say whether it is away about a /claim or an /afk typed on its transcript, where neither is offered while somebody else holds it. Lines said to the agents are never refused this way.

Fix. Ask them to /claim off, or wait for them to leave, which gives it back.

Verify. The outworlder's transcript no longer says <name>'s to answer under its question.

already answered by alice@tui

Symptom. Your answer to a question was refused.

Cause. Nobody had claimed that outworlder, so its question went to whoever answered first, and that was somebody else.

Fix. Nothing to do. If their answer was wrong, say so to the agent on its next turn.

Verify. Their answer is in the transcript, marked · by alice@tui.

hmz: the runs on this machine are held by an older Humanize (pid …); stop it with that version

Symptom. hmz will not open after an upgrade, or says the runs in <dir> instead.

Cause. The daemon an older Humanize started on this machine is still running, or a host one started for this directory is, and it speaks a protocol this version cannot read.

Fix. Open it with that version and stop it, or end the process named, then run hmz again.

Verify. hmz opens.

hmz: fell too far behind; open it again

Symptom. The interface closed with this.

Cause. It stopped taking what the host sent until it was a whole run behind, and was let go of. The run is untouched.

Fix. Run hmz again in the same directory.

Verify. It opens on the run, read from the top.

/btw requires a coding agent

Symptom. A /btw on the monitor is refused.

Cause. There, /btw asks the btw agent. None is set in /settings, and no flow is set up to copy one from. btw is still answering the last question means the side conversation has not answered yet.

Fix. Choose a flow, or set the /btw agent on the General page of /settings. For the second message, wait for the answer.

Verify. /btw opens the side conversation.

A line I typed did not reach the agent

Symptom. A line you typed stays pinned above the prompt, or ends in the transcript marked never sent.

Cause. A typed line goes to the agent you are reading. When you are reading all of them, it goes to whichever has a turn open. Until that agent takes it, the line stays pinned:

• Between turns, it waits for the next turn to start.
• Several lines go one at a time, so the later ones wait a turn or two.
• When the flow ends, lines nobody took move into the transcript marked never sent.
• Somebody else's lines wait beside yours, marked · by <name>, where another interface reads the same run.
• On an outworlder's transcript a line answers its question and is not said to an agent; with nothing asked, it is refused.

Fix. To send it to another agent, press shift+tab to read that one first. See Steering.

Verify. The pinned line goes, and the agent's transcript shows it taken.

The screen is unreadable in my terminal

Symptom. Text is hard or impossible to read against its background.

Cause. The interface draws in your terminal's own 16 colours, so the usual cause is a terminal theme with too little contrast between two of them.

Fix. Change the terminal's theme, or run NO_COLOR=1 hmz for no colour at all, or TEXTUAL_THEME=textual-dark hmz for a fixed palette.

Verify. The transcript and the status line read clearly.

The token count sits still, then jumps

Symptom. The readout above the prompt does not move during a turn, then jumps when it ends.

Cause. Some CLIs report tokens as each request to the model comes back; the others only at the end of each turn. An agent working on another machine reports at the end of each turn too. Cost and rate › When it moves lists which.

Fix. Nothing to do: the figure is right once the turn ends.

Verify. The count catches up at the turn's ✻ line.

Agents, accounts and models

A failed turn ends with what the CLI said, then the kind of failure in brackets:

Command 'claude' returned non-zero exit status 1. 429 rate limit exceeded
(throttled: the service asks it to slow down, with no quota spent; a wait is what answers it)

Humanize waits, retries, or moves to the next place of its fallback chain by itself, depending on the kind. The entries below say what is left for you to do. A failure with no brackets is one Humanize did not recognise, and it is retried as that place says. Under hmz exec, a failure nothing recovers from ends the run with a traceback whose last line is the same message, and exit status 1.

The agent fails on its first turn

Symptom. The first turn fails, with no bracket Humanize recognises, or with the CLI's own complaint about the model.

Cause. Usually a model that account cannot run. Humanize checks the effort before it starts, but only the CLI knows which models your account may use.

Fix. Run the CLI yourself with the same model, under the same account, and fix what it says. Then choose a model it runs.

Verify. The CLI answers on its own, and the next turn under Humanize does too.

(throttled: the service asks it to slow down, with no quota spent; a wait is what answers it)

Symptom. A turn fails with this bracket, and the run pauses or moves to another place.

Cause. The account hit its rate limit: the service is asking it to slow down, and has not said a quota is spent. Humanize waits, tries once more, then moves to the next place of the fallback chain, if there is one.

Fix. Give it one to move to: add an account on the Accounts page of /settings, and put a place under it (the same model under the new account, say) on the chain of the place that failed, on the Fallback page.

Verify. The next time it happens, the transcript says carrying on as the other place.

(spent: this account has spent its quota; another one, or a wait, is what answers it)

Symptom. A turn fails with this bracket, and the run pauses or moves to another place.

Cause. The provider said the account's quota or balance is used up (insufficient_quota, Quota exceeded, a credit balance too low, billing). Humanize answers it as it answers a rate limit: it waits, tries once more, then moves to the next place of the chain.

Fix. Top the account up, or wait for its quota to renew. Meanwhile give it somewhere to move to, as for a rate limit above.

Verify. The CLI answers under that account on its own again.

(refused: that account needs signing in again)

Symptom. A turn fails with this bracket.

Cause. The credential was refused, or the login expired. Humanize moves straight on to the next place of the fallback chain.

A login that renews itself (Codex with ChatGPT, Claude Code with a subscription) is also revoked, with refresh token was revoked, when two copies of it renewed apart: a copy of ~/.codex/auth.json or ~/.claude/.credentials.json put in a container, on another machine or in a test's temporary home. Humanize never makes one, but a copy made by hand does.

Fix. Sign the account back in, with the CLI's own login for the account this machine uses:

claude auth login
codex login

For an account Humanize keeps, type /settings accounts, choose the account, and pick sign in again. Then delete every copy of the file that was made, so it cannot happen again: on another machine, sign its CLI in there instead.

Verify. The CLI answers when you run it yourself, and the next turn goes through.

(fenced: the run's network fence keeps it off that host, which no sign-in answers; give the role online of ALL to let it through)

Symptom. A turn fails with this bracket, after the CLI said hmz: <host>:<port> is not a host this run may reach, often beside a 403 Forbidden.

Cause. The role has online of NONE, so its fence lets it reach only the hosts its model and login are at, and the CLI reached for another. Nothing was wrong with the account. Humanize moves straight on to the next place of the fallback chain.

Fix. Give the role online of ALL, or point it at a model whose host the fence knows.

Verify. The next turn goes through.

… this account signs in with a token that refreshes itself, and another turn is using it …

Symptom. A turn fails with this line, or with … and a copy of it is out on another machine for a turn there …, then with (contended: …) once its three tries are spent.

Cause. The role's @account is a login that renews itself, and the CLI of one of the turns using it runs on another machine (the runtime's harness env, the default). Two copies renewing apart get the login revoked, so a copy goes to another machine only while no other turn is using the account, and comes back renewed before any other turn may use it again. Turns on this machine share the one file and run side by side.

Fix. One of:

• give the roles that run at the same time an account each, or an account signed in with a key;
• set the harness of the runtime those roles work on to local, where every turn uses the one file in place;
• sign the CLI in on that machine and drop the @account.

Verify. The next turn starts. See Providers › A sign-in that refreshes itself.

(unlisted: … this account was last offered …)

Symptom. A turn fails because the account may not use that model. The bracket says whether Humanize's list of this account's models is out of date:

(unlisted: the 3 models this account was last offered (asked 2026-09-10) still list it, so
that list is stale; the "check again" button under its models checks again)

Cause. The account is signed in, but may not use that model. Humanize never asks an account again on its own.

Fix. In /flow, open the agent, open its model row, and press Check again under the models to ask the CLI what this account runs now. Then choose one of those.

Verify. The model is in the list Check again brings back, and the next turn goes through.

(retired: the model is gone or was never this account's; another place is what answers it)

Symptom. A turn fails with this bracket, and goes straight to the next fallback.

Cause. The CLI says there is no such model. No account of that CLI has it.

Fix. Choose another model: Check again, under the list the agent's model row opens, shows what the CLI runs.

Verify. The next turn goes through on the new model.

(missing: npm i -g @anthropic-ai/claude-code)

Symptom. A turn fails with this bracket, or … is not installed here: ….

Cause. The CLI is not installed where the agent runs, or would not start. The bracket holds the command that installs it.

Fix. Run that command, or see Installation.

Verify. command -v claude (or the CLI's own name) prints a path.

(sandboxed: this machine will not let it sandbox itself; run it without one, or somewhere it can)

Symptom. A turn fails with this bracket, usually with bwrap: … Permission denied just before.

Cause. The CLI could not start its own sandbox. An unprivileged container is the common cause.

Fix. Run it where the kernel allows unprivileged user namespaces, or give the role another CLI.

Verify. The turn starts.

(unmirrored: that path cannot be made here; …)

Symptom. A turn fails with this bracket, after cannot keep the local copy of the work at <path>: Permission denied: ….

Cause. The agent's CLI runs here and works in a copy of another machine's directory, kept at that directory's own path for an ssh environment, and that path cannot be made on this machine: a parent you may not write, or a file where a directory should be. No account was refused, and signing in again changes nothing.

Fix. Use a workdir whose path you can create here, or run the CLI on that machine by setting the harness of the runtime the work is on to env. See The path is taken here too.

Verify. The turn starts.

(contended: two turns of it are sharing one database)

Symptom. A turn of opencode or mimocode fails with this bracket.

Cause. Two turns wrote to the CLI's one database at once and got database is locked. Humanize retries three times, a second apart, which nearly always clears it. A turn of any CLI whose account is a login that renews itself can end here too, when another turn holds it the other way round: see the entry above.

Fix. If it keeps happening, run fewer of those agents at once.

Verify. The bracket stops appearing.

(killed: the machine it runs on may be out of memory)

Symptom. A turn fails with this bracket.

Cause. The CLI was killed rather than answering: out of memory, or a crash signal. Humanize waits a moment, reopens it and tries once more.

Fix. If it keeps happening, free memory or run fewer agents.

Verify. free -h shows room, and the bracket stops appearing.

(dropped)

Symptom. A turn fails with this bracket, then carries on.

Cause. The connection to the CLI or its service was lost. Humanize reopens it and resumes the same conversation.

Fix. Nothing, unless it keeps happening: then check this machine's network.

Verify. The next turn goes through.

the watchdog stopped this turn: claude is idle and has said nothing for 903s

Symptom. A turn is ended with this, and retried like any failed turn.

Cause. The CLI was still running but had gone silent, so Humanize ended the turn. The words before has said nothing say what it saw: is gone is a crash to look for in the CLI's own log, is stopped means something suspended it, and is idle means it was waiting on something that never answered. Humanize looks at a turn after 15 minutes of complete silence, 6 for DeepSeek Harness, and ends it unless the CLI is visibly busy.

Fix. If your turns really go quiet for longer, give them more room, in seconds, or 0 to turn this off:

HUMANIZE_WATCHDOG=3600 hmz

Verify. Long quiet turns finish instead of being stopped.

codex: this machine will not run an agent at bypass, so it runs at auto, where what it asks for is granted

Symptom. A note when a Codex agent starts. The work goes on.

Cause. This Codex has requirements set by whoever manages it, an enterprise policy or the machine's own, and they forbid full access. So the agent runs one permission rung down, at auto: Codex asks before it reaches past the workspace, and Humanize says yes.

Fix. Nothing to do.

Verify. The agent's turns go through as usual.

claude: this account will not run an agent at bypass, so it runs at acceptEdits, where what it asks for is granted

Symptom. A note during a Claude Code agent's first turn. The work goes on.

Cause. The Claude account's managed settings carry "disableBypassPermissionsMode": "disable", or Claude runs as root, so Claude will not run at bypassPermissions. The agent runs at acceptEdits instead: Claude asks before what that mode does not cover, and Humanize says yes.

Fix. Nothing to do.

Verify. The agent's turns go through as usual.

… cannot be held to its permission on this machine: it does not enforce it natively, and fencing it from outside needs …

Symptom. A role is refused before its first turn (HarnessSandboxed).

Cause. The role's permission is narrower than everything, and this machine cannot hold it: a Linux kernel older than 5.13 or booted without Landlock, or a Mac where Humanize itself runs inside another sandbox (an agent's own, say), which cannot start Seatbelt again. Cutting the network needs Linux 6.7 or later. A cursor-agent or mcode role whose online is NONE is refused on any machine, since its web search runs on its vendor's servers.

Fix. Run Humanize on a Linux machine with Landlock, or on a Mac outside any other sandbox, or give that role a CLI and a permission this machine can hold. The message says what is needed.

Verify. The role's first turn starts.

Exporting a run

… · 0 sessions, 0 slices

Symptom. export epic in /epics wrote the archive, but its trace holds nothing.

Cause. In order of likelihood:

1. The run ended before its first turn. /epics says how many sessions each run opened.
2. The agent was cursor-agent. Humanize cannot read its sessions into a trace. The rest of the archive is still there.
3. The run's sessions were moved or deleted since it ran.

Fix. For the first, there is nothing to trace: run again. For the second, watch a Cursor Agent run live on the monitor instead. For the third, restore the sessions if you have them.

Verify. Exporting again reports 1 session or more, and a count of slices.

Remote machines and containers

These come from an agent whose work lands on another machine: an ssh or docker environment given with -e, a container, or a remote execution target.

onbox needs an environment for 'box'; specify each with -e ROLE=BACKEND[@PROVIDER]/WORKDIR

Symptom. hmz exec refuses the line before anything runs.

Cause. The flow has an environment role that nothing on the line places.

Fix. Say where it is, with -e or at /flow:

-e box=ssh@build-box/home/me/build/myproject

Verify. The line gets past the check.

ralph_loop has no environment role 'box'; available roles are none

Symptom. hmz exec refuses an -e.

Cause. That flow only works in the directory you start it in. Most flows do.

Fix. Take the -e off, and start hmz exec in the project's directory; or use a flow written for another machine, as Remote execution shows.

Verify. The line gets past the check.

could not reach build-box over ssh: …

Symptom. The run is refused, or its first turn fails, with ssh's own words after the colon. there is no ssh host build-box: … means ssh could not resolve the name at all.

Cause. Humanize uses your own ssh config, agent and keys, and adds nothing. Whatever stops ssh build-box stops it too.

Fix. Run ssh build-box yourself and fix what it says: the host name, the key, the known_hosts entry. Reference › Remote execution has a check that walks the whole path to a target without starting an agent.

Verify. ssh build-box true returns with no prompt and exit status 0.

the workdir /home/me/build/myproject is not there

Symptom. The run is refused before any agent starts.

Cause. The directory -e names does not exist on that machine.

Fix. Put the project on the host at that path, or name the path it is at.

Verify. ssh build-box ls /home/me/build/myproject lists it.

… 'box' needs 8 GPUs, and the environment given has 0

Symptom. The run is refused before any agent starts.

Cause. The flow asks more of the machine, in CPUs, memory or GPUs, than it has.

Fix. Pick a machine that has it.

Verify. The line gets past the check.

docker@gpubox has 0 of 2 GPUs free, and 'box' asks for 1 …

Symptom. A docker role is refused before any agent starts. The message names every resource that is short (containers, CPUs, memory, GPUs) and which containers hold the rest.

Cause. The docker daemon saved as gpubox may hand out only so much, and running containers of Humanize's already hold it.

Fix. Wait for those runs to end, stop them, or give the daemon more to hand out on the runtimes page of /settings. A daemon that names no GPU says so: list its GPUs there.

Verify. The line gets past the check.

…: 'box' needs GitEnvMixin, which ssh@build-box/… does not support: GitEnvMixin needs git on the machine's PATH, and it has none

Symptom. The run is refused before any agent starts.

Cause. The flow works with git on that machine, and the machine has no git. GitWorktreeEnvMixin is refused the same way, and BashEnvMixin where the machine has no bash (… BashEnvMixin needs bash on the machine's PATH …).

Fix. Install git (or bash) there.

Verify. ssh build-box git --version prints a version.

ssh@build-box: claude's harness cannot run where its harness setting (env) says: claude is not installed on ssh@build-box: …

Symptom. hmz exec refuses the run with this before the flow starts, with exit status 2. The message ends … there, or set the harness of the runtime it is on to local.

Cause. The host's harness setting is env, the default and what a host nobody saved has: the agent's CLI runs on the host, and the host does not have it on the PATH its shell gives a command. Humanize does not run it anywhere else instead.

Fix. Install the CLI there, and sign it in there, with the line the message gives; or save the host with its harness local, to run the CLI here.

Verify. ssh build-box command -v claude prints a path, and the transcript at the prompt says builder's harness runs on its environment's machine.

… cannot fence the agent to its permission: it needs Landlock; grant the agent everything, or set the harness of the runtime it is on to local

Symptom. hmz exec refuses the run with this, after … harness cannot run where its harness setting (env) says: …, before the flow starts. … cannot fence the commands the agent runs there: it needs Landlock … is the same, for an agent whose CLI runs here.

Cause. The role's permission is narrower than everything, and the machine the work lands on cannot hold it: a kernel older than 5.13 or without Landlock, or a container whose seccomp profile refuses Landlock. Cutting the network needs Linux 6.7 or later there. A Mac target fences with Seatbelt, but an agent supervised here (its CLI runs here, its work there) needs Landlock on this machine too.

Fix. Set the runtime's harness to local, move the work to a machine with Landlock, or copy the flow and grant the role everything. Docker's default seccomp profile allows Landlock.

Verify. The role's first turn starts.

… a fence cannot hold a harness that runs on another machine

Symptom. hmz exec refuses the run with this, after … harness cannot run where its harness setting (ssh:gpu-box) says: …, before the flow starts, with exit status 2.

Cause. The harness setting of the runtime the work is on puts the CLI on another runtime, where Humanize cannot hold a permission narrower than everything. Only a role granted ALL in every scope can run that way; any other is refused.

Fix. Set the runtime's harness to local or env, or copy the flow and grant the role everything.

Verify. The run starts.

… a pre_tool_use hook cannot gate the tools of a CLI on another machine; set the harness of the runtime it is on to local

Symptom. hmz exec refuses the run with this, after … harness cannot run where its harness setting (env) says: …, before the flow starts, with exit status 2. It may name a permission_request hook as well, or instead.

Cause. The flow hangs a hook on the role that decides whether each tool runs. The CLI runs that hook as a program on this machine, so a CLI running on the host, as the runtime's harness env puts it, cannot be gated by it.

Fix. Set the harness of the runtime the work is on to local, so the CLI runs here.

Verify. The run starts, and the transcript at the prompt says <agent>'s harness runs here.

Humanize: no python 3.12 or newer on this machine; looked for: …

Symptom. The run fails when it first reaches the machine.

Cause. The target needs Python 3.12 or newer, and it has none that Humanize can find. It does not have to be on the PATH: the message lists every place Humanize looked.

Fix. Install Python 3.12 or newer there.

Verify. One of the places the message lists now holds a python3 that prints 3.12 or newer for --version.

could not install Humanize on docker://…: … is not running; the container said: …

Symptom. A container's first turn fails with this.

Cause. Humanize copies itself to a target before the agent starts, and this target refused. What it said follows the colon. A container that is not running stopped as soon as it started, which is what an image with no Python 3.12 or newer does: its last words say where it looked.

Fix. Use an image with Python 3.12 or newer.

Verify. docker run --rm <image> python3 --version prints 3.12 or newer.

Humanize: /tmp/humanize-… is not a directory this user owns

Symptom. The first turn on a docker target that names a user fails with this.

Cause. Humanize keeps its copy of itself, and a harness's mirrors, in directories of that user's own in the container (/tmp/humanize-<UID> and /tmp/humanize-mirrors-<UID>), and uses one only where it is a directory, not a link, that this user owns. Another user of the container made one of these first, or a link stands in its place.

Fix. Remove the directory the message names, in the container, as root or as its owner: docker exec -u 0 <container> rm -rf <dir>.

Verify. The turn starts, and docker exec <container> ls -ld /tmp/humanize-<UID> shows a drwx------ directory owned by that UID.

Humanize intercepts syscalls with a Linux seccomp filter and a ptrace supervisor, and this host is 'darwin'. …

Symptom. An agent whose work lands elsewhere will not start on a Mac.

Cause. An agent supervised here while its work lands elsewhere can only run on Linux.

Fix. Run Humanize inside a Linux virtual machine: Docker Desktop, colima and lima each give you one, on Intel and Apple silicon alike. The Mac can still be a target for an agent running somewhere else.

Verify. The same line, run in the Linux machine, starts the agent.

Humanize has a register map for aarch64, x86_64; this host reports 'riscv64', …

Symptom. An agent whose work lands elsewhere will not start on this machine.

Cause. An agent supervised here while its work lands elsewhere must run on an x86-64 or aarch64 Linux machine.

Fix. Run it from one of those. The target can be any architecture, this machine included.

Verify. The agent starts.

the target speaks protocol …, this Humanize speaks …

Symptom. The first turn on a target fails with this.

Cause. The two ends are different versions of Humanize, usually a target that was left listening before you upgraded.

Fix. Start it again with the Humanize you have now.

Verify. The turn starts.

unsupported target '…'; expected ssh://HOST, docker://CONTAINER[@ENDPOINT], apple-container://CONTAINER, slurm://JOBID[?python=PATH], tcp://HOST:PORT, peer://TICKET@HOST:PORT or local[:PATH]

Symptom. A target is refused.

Cause. Humanize cannot read the target as written.

Fix. Write it in one of the forms the message lists. peer:// is one Humanize writes for itself; you do not type it.

Verify. The target is accepted.

unsupported docker endpoint '…'; expected local, unix:///PATH, tcp://HOST:PORT[?tls=DIR], ssh://[USER@]HOST[:PORT][?KEYWORD=VALUE&...] or context:NAME

Symptom. A docker daemon is refused.

Cause. The daemon after a container's @, or in a saved docker environment's endpoint, is not one Humanize can read. A socket path and a ?tls= directory must be absolute.

Fix. Write it in one of the forms the message lists. See Endpoints.

Verify. Saving the daemon on the runtimes page of /settings checks it and succeeds.

no directory to give the container on …

Symptom. A container on a daemon elsewhere will not start.

Cause. The container is given the workspace at the path it has on that host, and that host has no such directory.

Fix. Make it there, or name one it has.

Verify. The container starts.

cannot listen on a non-loopback address without --token

Symptom. A target will not start listening.

Cause. A target listening on the network is a shell on that machine for anyone who reaches it.

Fix. Give --token a real secret, or use ssh:// or docker://, which open no port at all.

Verify. The target listens, and an agent given the token reaches it.

hmz: ignoring HUMANIZE_LOG='verbose', which is not one of debug, info, warning, error

Symptom. A turn on another machine, or hmz internal anchor run by hand, starts with this line on stderr.

Cause. HUMANIZE_LOG is set to something that is not a log level. It is ignored, and the command logs at its default level.

Fix. Set it to debug, info, warning or error, or unset it.

Verify. The line is gone.

… already contains files and is not a Humanize mirror. …

Symptom. An agent whose work lands elsewhere will not start.

Cause. The agent works in a local copy of the target at the same path, and Humanize replaces a copy's contents with the target's. So it will not take a directory holding other files, or one copying another target (… mirrors ssh://a, not ssh://b. …).

Fix. Use a path that is free on this machine, or an empty directory. Pass --force only if you mean the directory to be overwritten. The runtime's harness env runs the CLI on the target and needs no copy here. See Remote execution.

Verify. The agent starts.

A command ran against stale files

Symptom. A command on the target read a file as it was, not as the agent had just left it.

Cause. Only file contents reach the target. A permission change made through a file that is already open does not, and ownership, device nodes and extended attributes never do.

Fix. Make the change by a command run on the target instead. The full list is in Reference › Remote execution.

Verify. The next command sees the change.

could not start a container of python:3.12-slim on …: …

Symptom. A container will not start. Docker's own words follow.

Cause. Usually no Docker daemon to reach, an image that is not pulled, or an image with no shell in it.

Fix. Check docker info against that daemon, docker pull the image, or choose one with a shell.

Verify. docker run --rm <image> sh -c true succeeds.

no directory to give the container

Symptom. A container will not start.

Cause. The workspace directory does not exist. Humanize refuses rather than letting Docker create it, owned by root.

Fix. Create it first.

Verify. The container starts.

Containers left behind after a run was killed

Symptom. docker ps lists containers from runs that are over.

Cause. The run was killed before it could take them down: ctrl+c, kill and a hangup all let it take them down first, but a second ctrl+c, kill -9 or a machine that went down do not. The next run on the same daemon takes down those whose run has gone.

Fix. Every container Humanize starts is labelled with your uid, so this removes yours and nobody else's:

docker rm -f $(docker ps -q --filter label=humanize=$(id -u))

Verify. docker ps --filter label=humanize=$(id -u) lists nothing.

Writing a flow

For whoever wrote the flow. See Writing a flow.

… defines no flow

Symptom. -f names your file, and nothing is found in it.

Cause. Nothing in the module is decorated with @flow. A function is a flow because it is decorated, not because of its name.

Fix. Put @flow(...) on the function.

Verify. /flow lists it under local/.

… a flow is an `async def` function

Symptom. The flow is refused when it is loaded.

Cause. The function under @flow is a plain def.

Fix. Make it async def.

Verify. The flow loads.

Agents.reviewer: 'Reviewer' cannot be resolved: …

Symptom. The flow is refused when it is loaded.

Cause. The role's type is imported only under if TYPE_CHECKING:. Humanize reads the roles when the flow runs.

Fix. Import the type at runtime.

Verify. The flow loads, and /flow shows the role.

Still stuck

• Turn on details to see everything the agents do, and press ← for the monitor to see which one is doing what.
• Export the run from /epics and attach the archive to a bug report, with the output of hmz --version. Credentials are struck out, but your task and the agents' transcripts are in it.