Troubleshoot the AI agent
Start with the built-in checks. Inside the agent:
/doctor/statusFrom a shell:
champrep versionchamprep auth statuschamprep ai paths/doctor checks the installed version, sign-in, connection to CHAMPREP,
whether your plan includes the agent, whether rg (ripgrep) and git are
available, your shell, and terminal colour and size. /status shows your
profile, environment, model, permission mode, and local file locations.
Do not paste API keys, tokens, or unredacted logs into a support request.
“Not connected: run /login” or “not signed in”
Section titled ““Not connected: run /login” or “not signed in””The CLI has no valid sign-in for the active environment.
- Interactively, run
/loginorchamprep auth login. - In CI, check that
CHAMPREP_TOKENis set for the job.
Headless runs exit with code 3 in this case.
Local tools are not allowed
Section titled “Local tools are not allowed”The message mentions that local tools need the ai:agent scope. The
credential can use CHAMPREP AI but not the agent’s local tools.
- Sign in again with
champrep auth login. - For an API key, create a key that includes
ai:agentby name. A key with only broader scopes is not enough. See Sign in.
“The CHAMPREP CLI agent isn’t included in your plan”
Section titled ““The CHAMPREP CLI agent isn’t included in your plan””Your plan does not include the CHAMPREP CLI service. Other champrep
commands keep working. Upgrade using the link on the card, or see
Plans and limits.
If the message says a feature is turned off, or that your organization’s policy doesn’t allow it, an administrator of your organization controls it.
Rate limited or out of turns
Section titled “Rate limited or out of turns”- “You’re sending requests too quickly”: a per-minute limit. The agent retries automatically when the wait is short. In scripts, wait for the time in the hint before retrying.
- “You’ve used everything your plan includes for this period”: buy an
add-on or wait for the next billing period. Loops, subagents, and CI runs all
use turns, so check
/tasksfor anything still running.
The model can’t use tools
Section titled “The model can’t use tools”If you chose a model marked no tools, the agent can chat but cannot read
files, run commands, or use CHAMPREP services. Switch back with /model auto
or pick a model marked tools in /models. If a turn is refused because the
model lacks a capability, such as image input, choose Auto or another model
from the options shown. See Models.
A project’s commands, rules, or MCP servers are ignored
Section titled “A project’s commands, rules, or MCP servers are ignored”Content in .champrep/ stays inactive until you trust the repository. A
warning such as “allow rules and defaultMode are ignored until you trust this
project” means the project’s settings were found but not applied.
/trust/trust approveDeny rules always apply. See Repository trust.
“no such host” after upgrading from an early release
Section titled ““no such host” after upgrading from an early release”Early releases could write a Gateway address that is no longer in use into
config.toml. Current releases replace it automatically when they load the
configuration. If the error continues:
champrep config envchamprep config pathCheck that the active environment’s API URL is the CHAMPREP API Gateway and
not a custom or outdated address. To go back to the built-in default, remove
that environment’s section from config.toml; the CLI restores the built-in
environment the next time it runs, and you sign in to it again.
A file is “blocked by secret policy”
Section titled “A file is “blocked by secret policy””The file matches the built-in secret list or one of your deny_read rules, so
the agent cannot read it. This is intentional. Copy the non-secret parts into
another file, or use an example file such as .env.example. See
Secret protection.
Search is slow
Section titled “Search is slow”local_grep uses rg (ripgrep) when it is installed and falls back to a
slower built-in search otherwise. Install ripgrep and rerun /doctor.
The interactive agent does not start in a script
Section titled “The interactive agent does not start in a script”Interactive mode needs a terminal. In scripts and CI, use champrep ai -p.
See Headless and CI usage.
Where are my settings and logs?
Section titled “Where are my settings and logs?”champrep ai pathsThis prints every local file and folder the agent uses, including settings,
redacted debug logs, and checkpoints. Run the CLI with --debug for more
detailed logs. For CLI problems that are not specific to the agent, see
CLI troubleshooting.