Skip to content
Documentation

Troubleshoot the AI agent

Start with the built-in checks. Inside the agent:

/doctor
/status

From a shell:

Terminal window
champrep version
champrep auth status
champrep 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 /login or champrep auth login.
  • In CI, check that CHAMPREP_TOKEN is set for the job.

Headless runs exit with code 3 in this case.

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:agent by 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.

  • “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 /tasks for anything still running.

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 approve

Deny 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:

Terminal window
champrep config env
champrep config path

Check 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.

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.

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.

Terminal window
champrep ai paths

This 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.