Troubleshooting

First Checks

Start with:

opentraces status
opentraces doctor
opentraces doctor --security

status tells you what the current repo thinks is staged or waiting. doctor tells you whether required integrations are misconfigured.

Common Problems

Not Initialized

If the CLI says the repo is not initialized, run:

opentraces init

The current repo marker is .opentraces.json, not .opentraces/config.json.

No Traces Showing Up

Check:

opentraces status
opentraces list --stage inbox
opentraces setup claude-code

If you are using Claude Code, make sure the capture hooks are installed and that the repo has actual Claude Code session files under ~/.claude/projects/.

Blocked Traces

Inspect them with:

opentraces list --stage blocked
opentraces show <trace-id>

Then either redact, reset, or reject as needed:

opentraces redact <trace-id>
opentraces reset <trace-id>
opentraces reject <trace-id>

Push Fails

Common causes:

• no Hugging Face auth
• no remote configured
• --llm-review requested but staged traces do not have clean verdicts
• a configured integration is broken

Useful commands:

opentraces auth whoami
opentraces remote list
opentraces llm-review --scope staged
opentraces doctor

TruffleHog Enabled But Missing

If doctor reports that TruffleHog is enabled but unavailable:

opentraces setup trufflehog
# or
opentraces setup trufflehog --disable

LLM Review Unreachable

First check what doctor sees:

opentraces doctor --security

The LLM trace review row shows the configured backend and model, the endpoint URL, whether the api_key_env variable is set, and the probe result against that endpoint. Common signals:

• probe: ... not found — the configured model is not in the endpoint's catalog (pull it or update the model name)
• probe: UNREACHABLE ... — the endpoint did not respond (start the local server, check the URL)
• api key env: $VAR (unset) — remote backend needs an API key that is not exported in this shell

Re-test or reconfigure it:

opentraces setup llm-review --test
opentraces setup llm-review
opentraces setup llm-review --disable

Resetting A Repo

To remove opentraces from the current repo cleanly:

opentraces remove
opentraces remove --all

To clear the stored Hugging Face credential:

opentraces auth logout