-
Notifications
You must be signed in to change notification settings - Fork 0
Troubleshooting
Symptoms and what they usually mean. For anything not on this
page, commitbrief doctor is the first stop.
commitbrief doctor reports ✗ git binary on PATH. CommitBrief
shells out to git for several diff paths and cannot run without
it.
Fix: install git via your platform's package manager
(brew install git / apt install git / winget install Git.Git).
commitbrief doctor flags the active provider check (UC-03).
Means config.provider points at a provider whose api_key is
empty (or base_url for Ollama).
Fix: either run commitbrief setup again to fill in the
missing credential, or commitbrief providers use <name> to
switch to a provider that already has credentials.
Same root cause as above; surfaces later in the pipeline if
doctor was skipped. Check commitbrief providers list to see
which providers have keys.
You probably have two binaries on different points of $PATH.
Typically: the Homebrew install at /opt/homebrew/bin/commitbrief
and a go install build at ~/go/bin/commitbrief. The shell
finds whichever is earlier in $PATH.
Diagnose: which -a commitbrief lists every match.
Fix: either run the intended one with an explicit path
(~/go/bin/commitbrief --version), reorder $PATH, or uninstall
the one you do not want.
Output is being captured/piped through a tool that does not interpret ANSI. The logo prints to stderr and is suppressed when stderr is not a TTY — if you are seeing raw escapes, your stderr is a TTY but the surrounding tooling is rendering it wrong.
Workaround: the logo never goes to stdout, so
commitbrief --json | jq and commitbrief > out stay clean. If
you want the logo off in your terminal entirely, use
NO_COLOR=1 commitbrief (the gate fails closed under NO_COLOR).
CI surfaces a finding from one of CommitBrief's own quality checks; not a user-visible runtime issue. See the contribution docs for resolution.
The provider returned a response that did not parse as the v1 findings schema. CommitBrief retries once with a stricter nudge; a second failure degrades to markdown rendering and emits this warning.
The plain-text body is still useful as a manual review, but
--fail-on skips the threshold check (no structured findings to
evaluate) and surfaces:
ℹ --fail-on skipped: LLM produced unparseable output, no findings to evaluate.
Probable causes: model running too cold (rare for current API providers), prompt size near the context limit, Ollama with a small model that does not honor JSON mode well. Switch to a larger model or check whether the diff is near the context window.
Your diff touches files under .commitbrief/ and either you are
in a non-TTY context without --yes, or you answered no to the
guard prompt.
Why the guard fires: .commitbrief/ files are usually
user-specific (per-repo config, OUTPUT.md template) and
committing them may break other developers' configurations or
leak API keys.
Fix: if the change is legitimate, run with --yes (or accept
the prompt in TTY). If accidental, unstage the .commitbrief/
files: git restore --staged .commitbrief/.
The pre-send secret scanner found one or more credential-shaped strings on added lines. The scanner names the patterns but never prints the matched substring.
Fix: the most common cause is leaving a real key in source. Rotate the key, remove it from the diff (use environment variables, secret managers, etc.), and re-run.
If the match is a false positive (e.g. a test fixture), pass
--allow-secrets to bypass for this invocation, or set
guard.secret_scan: false if you have an external secret
scanner doing the job.
Cost preflight fired. Default threshold is $0.50.
Fix options: raise the threshold
(commitbrief config set cost.warn_threshold_usd 5.0), pass
--no-cost-check to skip the prompt, or trim the scope (e.g.
--file path/to/specific.go instead of --staged over a huge
diff).
Rare — should only affect gemini-cli for very large diffs (the
combined prompt exceeds the platform's ARG_MAX, typically
~128 KB).
Why: gemini-cli passes the prompt as an argv argument;
claude-cli switched to stdin transport in v0.9.2 (UC-24) and is
not affected.
Fix: for huge diffs, prefer claude-cli or one of the API
providers. The diff size limit is a host-CLI constraint, not a
CommitBrief limit.
Your repo-local or user-level OUTPUT.md does not parse or fails to execute against an empty / sample finding set. ADR-0014 §5 catches this before any provider call so a bad template does not burn tokens.
Fix: the error message includes the parse error from
text/template. Fix the syntax, or run commitbrief init --force
to overwrite with the embedded default.
See Installation for platform-specific notes:
- Homebrew formula update on stable releases only.
- Pre-release tags require
go install ...@<tag>or raw binary. -
~/go/binmust be on$PATHfor go-installed binaries to work.
commitbrief doctor # health-check everything
commitbrief dry-run --staged --verbose # inspect resolution + cost
commitbrief --version # confirm you are running what you think
commitbrief list # full reference + current config summary