/Troubleshooting
Reference

Troubleshooting

Common issues and how to fix them.

Claude Code Not Detected

Symptom: Setup screen shows Claude Code as not found, or a red warning in Settings.

Solutions:

  1. Open Terminal and run which claude — if it returns a path, copy it and enter it manually in Settings → Claude Code Path
  2. If which claude returns nothing, Claude Code is not installed. Install it from claude.ai/code
  3. If installed via Homebrew or npm in a custom location, check those directories and set the path manually

Claude Code Version Too Old

Symptom: OpenHelm reports your Claude Code version does not meet the minimum requirement (v2.0.0).

Solution: Update Claude Code. Run claude update in Terminal, or reinstall from claude.ai/code.

Jobs Not Running on Schedule

Symptom: Jobs are enabled with a valid schedule, but expected runs are not appearing.

Solutions:

  1. Is the app running? The scheduler only runs while OpenHelm is open
  2. Was your Mac awake? OpenHelm cannot wake a sleeping Mac — ensure your machine was on at the scheduled time
  3. Check the job's next fire time in the job detail view — if it's in the past, the scheduler will pick it up within 60 seconds
  4. Verify the job is enabled — the toggle on the job card must be on

Run Stuck in "Running" State

Symptom: A run shows as running but there is no new log output and it appears frozen.

Solutions:

  1. Wait up to 10 minutes — Claude Code may be silently processing or making API calls
  2. If still stuck after 10 minutes, cancel the run from the run detail view
  3. If the app was force-quit while a run was active, OpenHelm automatically marks orphaned running runs as failed on the next launch

Job Always Fails

Solutions:

  1. Check the run logs for the specific error message
  2. Ensure Claude Code can access the project directory — the path must exist and be readable
  3. Use Open in Terminal on a completed run to resume the Claude Code session and inspect what happened interactively
  4. Add a Correction note to the job with specific guidance for recovering from the failure

App Won't Open (Security Warning)

Solution:

  1. Right-click OpenHelm in Applications and choose Open (bypasses Gatekeeper on first launch)
  2. If still blocked: System Settings → Privacy & Security → scroll to the Security section → click Open Anyway

Getting Help