Troubleshooting
See also: Command · Configuration
rimba prints an actionable To fix: hint with most failures. Each section below shows the exact
error, why it happens, and the command to resolve it.
Committed shell commands require approval before running. Resolve approval errors and CI non-interactive flows.
Selecting worktreesErrors from rimba exec when no target selector or invalid type is provided.
Uncommitted-changes and push-rejection errors from rimba sync.
Flag-conflict errors when using rimba add in branch or PR mode.
Dirty-state errors that block rimba remove from discarding work.
Flag errors, permission failures, and worktree-directory creation problems from rimba init.
Missing config file and TOML syntax errors surfaced on every command invocation.
Debugging git operationsEnable --debug or RIMBA_DEBUG=1 to trace git commands and timings to stderr.
Quick reference — error message → page
| Error message | Page |
|---|---|
committed shell commands require approval |
Trust & consent gate |
committed shell commands are not trusted for this repo |
Trust & consent gate |
provide --all or --type to select worktrees |
Selecting worktrees |
invalid type "<x>"; valid types: ... |
Selecting worktrees |
--concurrency must be >= 0 |
Selecting worktrees |
worktree "<task>" has uncommitted changes |
Syncing |
push failed for <branch>: ... |
Syncing |
--source is not valid in branch: mode |
Adding / promoting |
--task requires a pr:<num> argument |
Adding / promoting |
<git error about dirty state> (remove) |
Removing |
--local requires --agents |
Init & setup |
--uninstall requires -g or --agents |
Init & setup |
failed to create worktree directory: ... |
Init & setup |
agent files: <error> |
Init & setup |
config not found: ... |
Configuration loading |
invalid config <file>: ... |
Configuration loading |