Troubleshooting

Error messages below are quoted as Jimothy shows them. Most step errors appear in red in the step header; the full context is in the step’s Logs tab (stderr lines are marked !). Trigger errors show on the Triggers page and as Trigger errors notifications.

Harnesses

"claude" not found on PATH / Failed to start claude: … ENOENT - is "claude" installed and on PATH?

The CLI isn’t installed, or Jimothy can’t find it. GUI apps don’t inherit your terminal’s PATH; Jimothy compensates by reading your login shell’s PATH and checking common install directories, but some setups (nvm/fnm-managed Node, custom prefixes, shells that set PATH only in interactive non-login config) still hide the binary.

1. In a terminal: which claude.
2. Add that directory to Settings → Execution → Extra PATH entries, click Save, then Harnesses → Re-detect.
3. Or set the harness’s Command to the absolute path.

Claude Code fails immediately when running as root

Claude Code refuses --dangerously-skip-permissions when run as root (containers, some Linux servers). Edit the Claude Code harness and replace --dangerously-skip-permissions with --permission-mode and acceptEdits (two lines), or run Jimothy as a regular user. See Claude Code.

<command> exited with code 1: …

The CLI ran and failed. The error includes the last five stderr lines. Common causes: the CLI isn’t signed in (run it once in a terminal), an unknown model id (pick one from the list or Default), a flag the installed version doesn’t support (edit the harness’s Arguments), or rate limits. For structured harnesses the step also fails if the CLI reports an error result even with exit code 0.

A step fails with Harness … is disabled — enable it on the Harnesses page or pick another harness

Re-enable the harness with its toggle on Harnesses, or choose another harness on the step.

Harness "x" is not configured

The step references a harness that no longer exists (a deleted custom harness, or an imported pipeline from a machine with other harnesses). Pick a harness on the step.

Timed out after N min

The step hit Timeout (minutes). The whole process tree was killed. Raise the timeout, or split the work into smaller steps.

API harness: Set an API key or ANTHROPIC_API_KEY

Detection didn’t find a key. Set API key on the harness, or make the variable available to the app. Keys set only in Settings → Environment variables work for runs but aren’t seen by detection or Fetch latest. See API harnesses.

API harness: Response hit max_tokens / The model declined this request (refusal)

Raise Max output tokens on the harness. For refusals, rephrase the prompt.

API harness: HTTP 404 … from localhost:11434

The base URL is wrong. OpenAI-compatible base URLs end in /v1 (Jimothy appends /chat/completions): http://localhost:11434/v1 for Ollama.

Model list: Set ANTHROPIC_API_KEY (or add it to the harness env) to fetch models from the Anthropic API

Claude Code’s model list comes from the Anthropic API. Either make ANTHROPIC_API_KEY available to the app, or skip fetching and type model ids. See Models.

The step ignores my subagents

The log shows <Harness> has no subagent flag configured; ignoring subagents …. Only harnesses with Subagent arguments receive subagents (Claude Code by default). See Custom harnesses.

Workspaces and git

Can't start: Workspace: choose the local git repository, or use "Existing folder" for a folder that isn't a git repo

The pipeline (or its project) uses Git worktree mode without a Local repository. Set it in Pipeline settings → Workspace (or the project’s workspace). Similar messages exist for Existing folder (choose the folder to work in) and Fresh clone (set the repository URL).

Workspace setup failed: … is not a git repository - use "Existing folder" mode …

Git worktree needs a git clone. Point it at one, or switch the workspace mode.

Workspace setup failed: git worktree failed: …

Look at the Setup & run log. Typical causes: the base branch doesn’t exist locally or on origin (set Base branch), or the repository is in a broken state. Jimothy first runs git fetch origin <base> (failure is tolerated), branches from origin/<base> if it exists or the local <base> otherwise, and adds -<run number> to the branch name if the branch already exists.

git push hangs or fails with “could not read Username”

Jimothy sets GIT_TERMINAL_PROMPT=0, so git never waits for a password prompt. Use SSH remotes with a key in your agent, a credential helper, or gh auth setup-git. For gh pr create, sign in with gh auth login or set GH_TOKEN in Settings → Environment variables.

gh: command not found

Install the GitHub CLI and make sure it’s on Jimothy’s PATH (see the first section).

Shell step quoting surprises

Template values in shell commands are quoted automatically. "{{issue.title}}" produces nested quotes; write {{issue.title}}. A command stored in a variable must use {{vars.testCommand | raw}}, otherwise it runs as a single quoted word ('npm test' → command not found). See Template variables.

Triggers

The trigger shows an HTTP 401 / 403 error

The account’s token was revoked, expired or lacks permissions. Open Accounts, edit the account, paste a new token and Save & re-verify. GitHub fine-grained tokens need access to the repository and Issues permission; organizations may need to approve the token.

No runs start

• Click Preview matching issues in the trigger editor. If it shows 0, the filter doesn’t match: check label spelling, Linear state names, GitHub Labels (all of), JQL.
• Is the trigger enabled (toggle) and its pill live?
• Were the issues already processed? The card shows N issues processed. Use the eraser (Forget processed issues) to reset.
• Linear with States empty only matches open states (not completed or canceled types).
• GitHub only looks at open issues, and not pull requests.
• Are runs queued behind Max concurrent runs or the pipeline’s own limit? Check Runs → Active.

Too many runs started at once

When a trigger is saved, every issue matching right now starts a run on the first poll (up to 50). Tighten the filter before enabling, then use Preview matching issues.

The same issue keeps running again

Run again when a processed issue is updated is on, and the issue still matches after its run. Jimothy’s own comments and transitions count as updates. Turn re-triggering off, or make the run move the issue out of the filter. See Polling & dedup.

Linear workflow state "In Review" not found

The write-back state name doesn’t exist in the issue’s team. Use the exact state name (case doesn’t matter).

No Jira transition to "In Review" (available: In Progress, Done)

Jira only allows certain transitions from the issue’s current status. Use one of the listed names, or change the workflow.

Invalid cron: …

See Schedule for the supported syntax. Names like MON aren’t supported.

Schedule didn’t fire

Jimothy must be running (the tray is enough) and the computer awake at that minute. Missed firings aren’t caught up. The expression is evaluated in local time.

Webhooks

Webhook server failed to start — Port 7717: … EADDRINUSE

Another process uses the port. Change Settings → Webhook server → Port.

Deliveries return 401 {"error":"invalid signature"}

• Linear: Webhook secret must be the Linear webhook’s signing secret.
• GitHub: the webhook’s Secret must match, and Content type must be application/json.
• Jira / generic: include ?token=<secret> (or X-Factory-Token, or Authorization: Bearer).
• A proxy that re-encodes the body breaks HMAC verification; tunnels like ngrok and cloudflared forward it untouched.

Deliveries return 202 {"ignored": true}

The event isn’t one the trigger acts on: a generic webhook without a title, a Linear event that isn’t an issue (or is a removal), a GitHub pull request or an action other than opened/labeled/reopened/assigned/edited, or an issue that fails the trigger’s label/team/state filters.

Deliveries return 404 or 409

404 unknown trigger: the id in the URL is wrong (copy it from the trigger editor). 409 trigger disabled: switch the trigger on.

Runs

Interrupted: the app was closed while this run was in progress. Use Retry to resume.

Jimothy was quit (or crashed) during the run. Retry re-runs unfinished steps in the same workspace.

Cancel the run before deleting it

Active runs can’t be deleted. Cancel first.

Verdict: output did not match pass pattern /…/

The step’s output didn’t contain what Pass if output matches (regex) expects. Check the Output tab; the model may have phrased the verdict differently. Patterns are case-insensitive and multiline (im flags).

… (feedback loop limit of 2 reached)

The loop ran Max loops times and the step still failed. Raise Max loops or look at why the reviewer keeps rejecting.

Run stuck in awaiting approval

Approval steps wait indefinitely. Approve or reject on the run page (or from your phone with remote access), or cancel the run.

Remote access

See Remote access → Troubleshooting.

Secrets are empty after moving to a new machine

Encrypted secrets are tied to the original machine’s OS keychain and load as empty elsewhere. Re-enter tokens on Accounts, API keys on Harnesses, and channel URLs on Notifications. See Data & security.