troubleshooting.md

title	Troubleshooting
nav_order	4
has_children	true

Troubleshooting

See also: [Command]({{ '/commands' | relative_url }}) · [Configuration]({{ '/configuration' | relative_url }})

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. {: .fs-6 .fw-300 }

---

Trust & consent gate

Committed shell commands require approval before running. Resolve approval errors and CI non-interactive flows.

Selecting worktrees

Errors from rimba exec when no target selector or invalid type is provided.

Syncing

Uncommitted-changes and push-rejection errors from rimba sync.

Adding / promoting

Flag-conflict errors when using rimba add in branch or PR mode.

Removing

Dirty-state errors that block rimba remove from discarding work.

Init & setup

Flag errors, permission failures, and worktree-directory creation problems from rimba init.

Configuration loading

Missing config file and TOML syntax errors surfaced on every command invocation.

Debugging git operations

Enable --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]({{ '/troubleshooting/trust-consent'
committed shell commands are not trusted for this repo	[Trust & consent gate]({{ '/troubleshooting/trust-consent'
provide --all or --type to select worktrees	[Selecting worktrees]({{ '/troubleshooting/selecting-worktrees'
invalid type "<x>"; valid types: ...	[Selecting worktrees]({{ '/troubleshooting/selecting-worktrees'
--concurrency must be >= 0	[Selecting worktrees]({{ '/troubleshooting/selecting-worktrees'
worktree "<task>" has uncommitted changes	[Syncing]({{ '/troubleshooting/syncing'
push failed for <branch>: ...	[Syncing]({{ '/troubleshooting/syncing'
--source is not valid in branch: mode	[Adding / promoting]({{ '/troubleshooting/adding-promoting'
--task requires a pr:<num> argument	[Adding / promoting]({{ '/troubleshooting/adding-promoting'
<git error about dirty state> (remove)	[Removing]({{ '/troubleshooting/removing'
--local requires --agents	[Init & setup]({{ '/troubleshooting/init-setup'
--uninstall requires -g or --agents	[Init & setup]({{ '/troubleshooting/init-setup'
failed to create worktree directory: ...	[Init & setup]({{ '/troubleshooting/init-setup'
agent files: <error>	[Init & setup]({{ '/troubleshooting/init-setup'
config not found: ...	[Configuration loading]({{ '/troubleshooting/configuration-loading'
invalid config <file>: ...	[Configuration loading]({{ '/troubleshooting/configuration-loading'