> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Find quick solutions for the most common problems and errors when using ChatCLI.

Found a problem? This page lists the most common errors and how to fix them.

<Tip>
  For more detailed diagnostics, enable debug logging: `LOG_LEVEL=debug chatcli`
</Tip>

***

## Common Problems

<AccordionGroup>
  <Accordion title="chatcli command not found" icon="terminal">
    **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:

    ```bash theme={"system"}
    export PATH=$PATH:$(go env GOPATH)/bin
    ```

    3. Restart your terminal or run `source ~/.zshrc`
  </Accordion>

  <Accordion title="Error &#x22;No LLM provider is configured&#x22;" icon="key">
    **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:

    ```env theme={"system"}
    LLM_PROVIDER=OPENAI
    OPENAI_API_KEY="sk-your-secret-key-here"
    ```

    3. Save and run `chatcli` again
  </Accordion>

  <Accordion title="Changes to .env have no effect" icon="rotate">
    **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.

    ```bash theme={"system"}
    /reload
    ```
  </Accordion>

  <Accordion title="@file cannot find a file/directory" icon="file-circle-exclamation">
    **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
  </Accordion>

  <Accordion title="Agent Mode does not execute anything" icon="robot">
    **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
  </Accordion>

  <Accordion title="Ollama provider is not detected" icon="server">
    **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`:

    ```env theme={"system"}
    OLLAMA_BASE_URL="http://localhost:11434"
    ```
  </Accordion>

  <Accordion title="Truncated or incomplete responses" icon="scissors">
    **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`:

    ```env theme={"system"}
    OPENAI_MAX_TOKENS=60000
    ANTHROPIC_MAX_TOKENS=20000
    GOOGLEAI_MAX_TOKENS=50000
    ```
  </Accordion>

  <Accordion title="API call timeout" icon="clock">
    **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](/features/provider-fallback) for redundancy
  </Accordion>

  <Accordion title="Agent needs to create a temporary file but /coder blocks it">
    `/coder` mode validates that every write happens inside the project directory. Starting with this release, ChatCLI creates a [Session Workspace](/features/session-workspace) at `$TMPDIR/chatcli-agent-<random>/` that is automatically on the allowlist:

    ```xml theme={"system"}
    <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.
  </Accordion>

  <Accordion title="Tool result truncated but I cannot see the full content">
    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`:

    ```xml theme={"system"}
    <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](/features/tool-result-management).
  </Accordion>

  <Accordion title="A /metrics endpoint or huge log saturates the context">
    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](/features/web-tools#filters-for-large-payloads).
    2. **Subagent delegation** — `delegate_subagent` runs the analysis in an isolated context window and returns only the summary. See [Subagent Delegation](/features/subagent-delegation).
  </Accordion>

  <Accordion title="Subagent refuses to run with 'subagent depth N exceeds maximum'">
    You reached the nested-delegation limit (default 2). Common cause: a subagent delegating to another subagent in a loop. Increase carefully:

    ```bash theme={"system"}
    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.
  </Accordion>
</AccordionGroup>

***

## Still having problems?

<CardGroup cols={2}>
  <Card title="Debug Logs" icon="bug">
    Run with `LOG_LEVEL=debug` and check `~/.chatcli/app.log` for full error details.
  </Card>

  <Card title="Open an Issue" icon="github" href="https://github.com/diillson/chatcli/issues">
    Include: version (`chatcli --version`), OS, Go version, steps to reproduce, and relevant logs.
  </Card>
</CardGroup>