Skip to main content
Found a problem? This page lists the most common errors and how to fix them.
For more detailed diagnostics, enable debug logging: LOG_LEVEL=debug chatcli

​
Common Problems

Symptoms: bash: chatcli: command not found or zsh: command not found: chatcli.Cause: The Go binary directory is not in your system’s PATH.Solution:
  1. Open your shell configuration file (~/.bashrc, ~/.zshrc, etc.)
  2. Add the following to the end of the file:
export PATH=$PATH:$(go env GOPATH)/bin
  1. Restart your terminal or run source ~/.zshrc
Symptoms: ChatCLI terminates immediately after starting.Cause: No API key has been configured in the .env file.Solution:
  1. Create or open the .env file in the directory where you run chatcli (or in your HOME)
  2. Add credentials for at least one provider:
LLM_PROVIDER=OPENAI
OPENAI_API_KEY="sk-your-secret-key-here"
  1. Save and run chatcli again
Symptoms: You changed LLM_PROVIDER or another value, but ChatCLI uses the old configuration.Cause: ChatCLI loads configuration at startup.Solution: Use the /reload command within interactive mode to reload variables instantly.
/reload
Symptoms: Error “file does not exist” or “path not found”.Solution:
  • Relative Paths — are relative to the directory where you ran chatcli. E.g.: @file ./project/src/main.go
  • Home (~) — works as a shortcut: @file ~/documents/notes.txt
  • Permissions — check with ls -l that you have read permission on the file
Symptoms: The AI presents an action plan but just waits without executing.Cause: This is the expected behavior! Agent Mode requires explicit approval.Solution:
  • Type the command number (e.g., 1) to execute it individually
  • Type a to execute all commands in sequence
  • Use --agent-auto-exec in one-shot mode for automatic execution of safe commands
Symptoms: Even with OLLAMA_ENABLED=true, the provider does not appear available.Solution:
  1. Ollama Server — confirm it is running: ollama serve
  2. Model downloaded — check with ollama list. If empty, download one: ollama pull llama3
  3. Base URL — if not at the default address, set it in the .env:
OLLAMA_BASE_URL="http://localhost:11434"
Symptoms: The AI response stops in the middle of a sentence.Cause: The response token limit was reached.Solution: Increase the MAX_TOKENS for your provider in the .env:
OPENAI_MAX_TOKENS=60000
ANTHROPIC_MAX_TOKENS=20000
GOOGLEAI_MAX_TOKENS=50000
Symptoms: Timeout error or the application hangs waiting for a response.Solution:
  • Use --timeout to set a limit: chatcli -p "question" --timeout 60s
  • Configure MAX_RETRIES and INITIAL_BACKOFF in the .env for automatic retries
  • Consider configuring Provider Fallback for redundancy
/coder mode validates that every write happens inside the project directory. Starting with this release, ChatCLI creates a Session Workspace at $TMPDIR/chatcli-agent-<random>/ that is automatically on the allowlist:
<tool_call name="@coder" args='{"cmd":"exec","args":{"cmd":"cat > $CHATCLI_AGENT_TMPDIR/script.sh <<EOF\n...\nEOF\nbash $CHATCLI_AGENT_TMPDIR/script.sh"}}' />
For writes via write or patch, use the absolute path that appears in the system prompt (the $CHATCLI_AGENT_TMPDIR variable is not expanded inside the file argument).Cleanup runs automatically on exit; set CHATCLI_AGENT_KEEP_TMPDIR=true to preserve and inspect.
When the budget cuts an output and shows [full output saved to /tmp/chatcli-agent-XXX/tool-results/...], the path is on the agent’s read allowlist. Just open it with read_file:
<tool_call name="@coder" args='{"cmd":"read","args":{"file":"/tmp/chatcli-agent-XXX/tool-results/budget_tc_3_1.txt","start":1200,"end":1500}}' />
Do not re-run the original tool call — the content is already on disk. Details in Tool Result Management.
Two complementary strategies:
  1. @webfetch filters — pass filter, exclude, from_line/to_line to filter before truncation, or save_to_file: true to persist the body to the scratch dir and read slices later with read_file. See Web Tools.
  2. Subagent delegation — delegate_subagent runs the analysis in an isolated context window and returns only the summary. See Subagent Delegation.
You reached the nested-delegation limit (default 2). Common cause: a subagent delegating to another subagent in a loop. Increase carefully:
CHATCLI_AGENT_SUBAGENT_MAX_DEPTH=3 chatcli
But consider whether the task wouldn’t fit better in a single delegation with a more explicit prompt about what needs to be done.

​
Still having problems?

Debug Logs

Run with LOG_LEVEL=debug and check ~/.chatcli/app.log for full error details.

Open an Issue

Include: version (chatcli --version), OS, Go version, steps to reproduce, and relevant logs.