Troubleshooting
Agents and sessions
A pane that disconnects, an agent that stops, a budget that runs out, and a second engine.
The pane says it is reconnecting
The transport dropped. The page pings every 15 seconds, treats 40 seconds of silence as dead, and re-attaches to the same terminal, backing off through 400ms, 900ms, 2s, 4s, 8s and then 15s.
The pane closed and will not come back
Three close codes mean the session is over and are never retried: 1000 when the board closed the pane, 4404 when there is no session for that agent, and 4500 when a pane could not be opened.
Click the agent to open a new pane.
no session
The close reason behind code 4404.
no agent named ‘x’ in this workspace
The named agent is not in this workspace’s roster.
x has no home at
The agent is in the roster but its home folder is missing. Run torta sync,
or check the workspace was copied whole.
no pane is open for this agent
Status 409 from the pane routes that write into a session. Open the pane.
the pane is open but would not take the prompt
Status 409 from a delivery. If the session has exited, close the pane and let the engine open a fresh one.
the board is shutting down
No new pane opens once shutdown has begun, and every pane closes with the board.
An agent stopped and is asking me something
Answer it in the needs-you lane, or with torta approve: the two are the same
call. The five questions torta can ask are listed in
approvals and the needs-you lane.
A ticket went to BLOCKED
Two things put a ticket there:
- a hard constraint, meaning impossible as specified, not merely slow or awkward
- a budget breach, in which case the ticket carries the limit that tripped and the cost so far
The session stops with the limit named, the tool call that would cross it is
denied, and a budget_breach event is written to .torta/events.jsonl. From
BLOCKED you can send it to NOT_FEASIBLE or back to APPROVED.
Raise the limits in torta.json under workflow.sessionBudgets. The defaults
are 30 minutes of wall clock, 200000 tokens, 200 tool calls and 8
continuations.
A ticket delivered into a board pane carries no token or tool-call budget, and
the delivery is logged as a pane_deliver event.
Nothing is being started
The dispatcher records its reason, in the order it checks them:
| What it says | What to do |
|---|---|
| kill switch | the engine is paused, press resume |
| at cap (3) | three sessions are already running |
| cooling down | that agent finished a session under 60 seconds ago |
| already running | it has a session now |
| waiting on a decision from you | answer it in the needs-you lane |
wip/ holds <file> — one ticket at a time |
let that ticket move on |
Also check that an engine is running: torta board runs none,
torta start --no-engine turns it off, and the header says which.
An engine is already running for this workspace
The refusal names the command that holds it, its pid and its start time. Stop
it, or run torta start --no-engine for a board beside it.
A ticket is stuck in wip after a crash
The engine reclaims it. A lock whose heartbeat is older than 120 seconds
belongs to a session that is gone, so the next tick takes the ticket back and
writes a lease_reclaim event.
A reclaimed wip ticket outranks everything queued on the next pass.
If you are working the ticket by hand, say so, and nothing starts in that home:
torta watch --busy frontendunknown runner ‘x’
The four are stub, sdk, pty and auto.
–cap takes a whole number of concurrent sessions
At least 1.
–busy names an agent that is not in the roster
The refusal prints the roster.