Troubleshooting
When something goes wrong, Irie shows it in the row’s mark, and says why in the line under the list. irie ctl list shows the same line under DETAIL, and irie ctl list --json adds the last lines of the agent’s screen.
Stalled
stalled: no hooks within 30s · <the last line on the agent’s screen>The agent didn’t report in within spawn.ready_timeout, 30 seconds unless you changed it. Usually it’s waiting for you at the start: to trust the folder, to sign in, or to accept something on its first run.
- Show the row and answer the agent on its screen. The row turns to working once the agent starts.
- Trusting a repo once covers all its worktrees.
- If your agent is only slow to start, raise
spawn.ready_timeout, such as to"60s".
Failed
failed: exit 127 · irie: claude: command not foundThe agent’s program ended before it got going. Its exit code and its last screen line say why.
| The line ends with | What to do |
|---|---|
exit 127 · irie: claude: command not found | Irie couldn’t find the program. Install it, or put its full path in the profile’s command. Irie’s tmux keeps the PATH it started with, so a folder you added since isn’t searched. |
| Claude Code’s own message about a model, effort or permission mode | Claude Code turned down a value in the profile, such as a model your account can’t use. Change the profile, then restart the core. |
exit 126 · irie host: … | Irie couldn’t read the session’s launch file. Start the task again, and report a bug if it happens again. |
The agent’s last screen stays: show the row to read all of it.
Needs you
| The line says | What happened | What to do |
|---|---|---|
asks: … | The agent asked you a question. | Show it and answer. |
needs permission: … | It wants your go-ahead for a step, such as a command. | Show it, then allow or refuse. |
wants the plan approved | It made a plan, and waits for you. | Show it and decide. |
… asks: … | A tool server the agent uses wants your input. | Show it and answer. |
turn failed: rate_limit | Claude Code hit a usage limit. | Wait until the limit resets, or start the task again on another profile. |
turn failed: authentication_failed | Claude Code’s sign-in failed. | Sign in to Claude Code again, then show the row and carry on. |
turn failed: billing_error | A problem with your account’s billing. | Check your account. |
The row goes back to working at the agent’s next step. Moving a task to another profile when it hits a usage limit is planned. Planned
Exited
exited 1The agent’s program ended after it got going, for example because you quit it. The mark is red if it ended with an error, and Claude Code’s reason, when it gives one, follows the code.
The last screen stays: show the row to read it. An ended row stays in the list, since closing rows, and reopening one with its conversation, are planned. Planned
A row that always says working
Agents from a generic profile don’t report in, so Irie knows only whether their program is still running. Their rows show working until the program ends, then exited.
core offline
The list can’t reach Irie’s core. Irie restarts the core on its own, waiting a little longer each time, up to 30 seconds, and the list tries again every second.
If it stays offline, run irie up in another terminal, and read the end of ~/.local/state/irie/core.log.
Messages from irie
| Message | What to do |
|---|---|
Irie is not running; `irie up` starts it | irie ctl list, show and watch need a running Irie. Run irie up. |
already inside tmux; run `irie attach --nested` to open Irie inside it | Run irie outside tmux, or add --nested. |
tmux not found: install it or set tmux.path | Install tmux, or set tmux.path to its full path. |
the core did not answer within 5s (…); see …/core.log | The core didn’t start. The log says why. |
config …: unknown key "…" | A setting Irie doesn’t know: a typo, or one from a later milestone. Fix or remove it. |
config …: spawn.default_profile = "fast": no such profile | A value that makes no sense. The message names the setting and what it must be. |
When a task won’t start
Nothing starts, and the line under the list turns red. From irie ctl spawn, the same message ends the command.
| Message | What to do |
|---|---|
no repo named @shp; closest: @shop | Use one of the names it suggests, or give the folder. |
no repo named @shop, and no repos are known: … | Tell Irie where your projects live, with repos.roots, or give the folder. |
@shop fits 2 repos: …; give the path of the one you mean | Give the folder of the one you mean. |
… has no commits yet: commit once, or add ! to run in the checkout itself | A worktree needs a commit to start from. |
worktree.base "…" is not a commit in … | Point worktree.base at a commit that repo has. |
@…: no such directory: … | The folder doesn’t exist. |
@./shop: give an absolute path, a ~/ path or a repo name | Write the folder from ~/ or /. |
no profile +fast; the profiles are claude, local | Use one of those, or add the profile and restart the core. |
only one +profile per task, only one @ target per task | Keep one of each. |
empty task | Write a task after the @ and + words. |
unknown command :pause | Commands that start with : are planned. Planned |
paste too long for the command bar (… lines); … | The box holds 10,000 lines at most. Save the text to a file and name the file in the task. |
git worktree add …: … | git couldn’t make the worktree; the rest is git’s own message. |
Warnings after a start
These show in the line under the list once a task starts, and irie ctl list --json lists them under warnings. The agent runs anyway.
| Warning | What it means |
|---|---|
1 uncommitted change in the main checkout was not carried over | Changes you hadn’t committed stayed in your checkout. Commit them, and start again if the agent needs them. |
.env not copied: …, no local files copied: … | A local file couldn’t be copied into the worktree. |
submodules not checked out: … | git couldn’t check out the repo’s submodules in the worktree. |
pause off: Claude Code … is older than 2.1.295 | Pausing agents will need Claude Code 2.1.295 or later; nothing else changes today. Planned |
--name left out: `claude --help` does not list it | Your Claude Code doesn’t take --name, so its own session isn’t named after the row. |
Every step blocked after moving irie
Agents report to Irie through irie, by the path it had when they started. If you moved or deleted it, Claude Code 2.1.295 and later block their steps: put irie back, or build it again in the same place with go install.
Where Irie keeps things
| Path | What’s there |
|---|---|
~/.config/irie/config.toml | Your settings, if you made the file. |
~/.local/state/irie/core.log, ui.log | What the core and the list did, with their errors. |
~/.local/state/irie/journal/ | Every event, one file per day, kept for 30 days. |
~/.local/state/irie/sessions/<id>/ | Each session’s task, task.md; how it was started, spec.json; Irie’s hooks for it, claude-settings.json; and how it ended, exit.json. |
~/.local/state/irie/tmux.conf | Irie’s own tmux settings, written for you. |
~/.local/share/irie/scratch/ | The folders of tasks that named no project. |
~/.local/share/irie/worktrees/ | Worktrees, a folder per repo. |
With XDG_CONFIG_HOME, XDG_STATE_HOME or XDG_DATA_HOME set, these live in those folders instead. Scratch folders and worktrees stay until you remove them.
Still stuck?
Search the issues, then report a bug. Give irie version, your system, tmux -V and claude --version, and the lines of core.log from around the time, with anything private taken out.
For a security problem, don’t open an issue: see SECURITY.md.