Troubleshooting

Common fixes for install, version, API, and runtime problems.

Wrong version

Check your installed version and location. If Homebrew upgraded Harper but the version still looks old, another binary is earlier in your PATH.

which harper

harper --version

$(brew --prefix)/bin/harper --version

If which harper points to ~/.local/bin/harper, use Settings -> Execution Policy -> Updates -> Fix Homebrew PATH, or run:

backup="$HOME/.local/bin/harper.old"; i=1; while [ -e "$backup" ]; do backup="$HOME/.local/bin/harper.old.$i"; i=$((i + 1)); done
mv "$HOME/.local/bin/harper" "$backup"
ln -sfn "$(brew --prefix)/bin/harper" "$HOME/.local/bin/harper"
hash -r

brew upgrade harpertoken/tap/harper-ai

Multiple installations

Find all harper binaries on your system.

find /usr/local/bin ~/.local/bin $HOME -name "harper" 2>/dev/null

Server is not reachable

If editor integrations or API requests fail, confirm the local server is actually running and listening on the expected port.

curl http://127.0.0.1:8081/health

If that fails, start Harper with the server enabled in config, then run the TUI normally.

Wrong provider or missing responses

If requests hang or fail immediately, check provider settings in config/local.toml and make sure the selected model endpoint is reachable from your machine. For local offline setups, confirm Ollama is running before starting Harper. Current Harper builds also return a clear assistant reply when the model backend is unavailable and no deterministic fallback exists, so a clean failure usually points to provider reachability or configuration rather than a silent UI problem.

No visible reply indicator

If the assistant looks idle after you send a message, update to a recent build. Current TUI builds show a visible in-thread Thinking... row while the worker is waiting on a reply, plus header activity state for longer tool and approval flows.

Sandbox or command approval confusion

If a command does not run, check whether it was blocked by policy, waiting for approval, or denied by sandbox rules. Harper is designed to stop rather than silently escalate.

Routing or follow-up behavior looks wrong

Do not start in the TUI. Verify the same prompt through the shell harness first so you can see the selected strategy, task mode, deterministic intent, normalized command, activity, and final assistant reply without UI state in the way.

cargo run -p harper-ui --bin harper-batch -- --strategy deterministic --prompt "where is execution strategy used in this repo"
cargo run -p harper-ui --bin harper-batch -- --strategy deterministic --prompt "run the git status" --prompt "run that"
cargo run -p harper-ui --bin harper-batch -- --strategy grounded --prompt "where is execution strategy used in this repo"

Read ROUTING, DETERMINISTIC INTENT, NORMALIZED COMMAND, ACTIVITY, and ASSISTANT first. If the shell path is wrong, fix core routing. If the shell path is right and the TUI still looks wrong, the problem is in UI state or rendering.

Build issues while developing

For local development problems, run the repository validation script first. It matches the current repo workflow more closely than an ad hoc sequence of Rust commands.

bash scripts/validate.sh

If you need to run commands by hand after that, use the same narrow checks Harper expects in development, including the full workspace clippy invocation with warnings denied.

cargo check --workspace
cargo clippy --all-targets --all-features --workspace -- -A clippy::pedantic -D warnings
cargo test --workspace