> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging.poolside.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot Poolside Agent CLI

> Diagnose common Poolside Agent CLI authentication, configuration, and ACP issues.

Use this page when `pool` starts but a session, prompt, or editor connection fails.

Run troubleshooting commands in your terminal shell, not inside the interactive `pool` prompt or an editor chat panel. To leave an interactive `pool` session, type `/quit` or press `Ctrl+C` twice.

<Info>
  This documentation describes Poolside Agent CLI v1.0.6. Check your version with `pool --version`. To update, exit any active session and run `pool update` from your terminal. See [pool CLI releases on GitHub](https://github.com/poolsideai/pool/releases) for release history.
</Info>

## Check which files Poolside uses

Run:

```bash theme={null}
pool config
```

The output shows the log directory, trajectory directory, config directory, and credentials path that `pool` is using.

By default, Poolside stores configuration files in `~/.config/poolside`. For more information about configuration and credential files, see [Install Poolside Agent CLI](/cli/install#configure-and-inspect-paths).

## Fix API key or token errors

Use this section when you see an error such as:

* `403 Forbidden: please check the api-key you provided`
* `401 Unauthorized`
* `Error during ACP method session/prompt`

These errors usually mean the prompt reached the agent, but the agent or model request could not authenticate.

### Steps

1. Check whether authentication environment variables are set.

   ```bash theme={null}
   env | grep -E '^POOLSIDE_(API_KEY|TOKEN|STANDALONE_BASE_URL|STANDALONE_MODEL)=' | sed 's/=.*/=<set>/'
   ```

   This command shows whether a variable is set without printing the secret value.

2. If any of those variables are set, test without them.

   ```bash theme={null}
   env -u POOLSIDE_API_KEY -u POOLSIDE_TOKEN -u POOLSIDE_STANDALONE_BASE_URL -u POOLSIDE_STANDALONE_MODEL pool
   ```

3. Sign in again.

   ```bash theme={null}
   pool logout
   pool login
   ```

4. Choose the login flow that matches your environment:

   * **Log in with Poolside Platform**: Use the public standalone Poolside flow. This opens `platform.poolside.ai` and asks you to paste a Poolside API key.
   * **Log in with OpenRouter**: Use this when you want `pool` to connect to models through OpenRouter. Enter an API key from [OpenRouter API keys](https://openrouter.ai/keys).
   * **Log in to an existing Poolside tenant (enterprise)**: Use this only when you need to connect to a specific Poolside deployment.

   If you already know the Poolside deployment URL, you can start the tenant login flow directly:

   ```bash theme={null}
   pool login --api-url <api-url>
   ```

5. Start a new session and send a short text prompt.

   ```bash theme={null}
   pool
   ```

   If the short prompt works, retry the original workflow. If the short prompt still returns an API key or token error, the saved credentials or selected environment are not valid for the endpoint you are using.

## Check feature behavior and authentication

Some feature tests can reach authentication later during prompt submission. For example, when you paste an image with `Ctrl+V`, the image paste succeeds if the prompt input box shows an image attachment before you submit. If the prompt later returns `403 Forbidden: please check the api-key you provided`, troubleshoot authentication instead of image paste.

## Troubleshoot editor ACP connections

If `pool` is running through an Agent Client Protocol (ACP) editor integration, check the ACP logs:

```bash theme={null}
pool acp logs -f
```

For formatted logs, run:

```bash theme={null}
pool acp logs --pretty
```

Common ACP issues:

* **`pool` not found**: Add `pool` to your `PATH`, use the full path to the binary in your editor configuration, or run `pool.exe` on Windows if your shell does not resolve `.exe` commands.
* **Authentication errors in standalone mode**: Run `pool login`, choose **Log in with Poolside Platform** or **Log in with OpenRouter**, then reconnect.
* **Authentication errors when connected to a Poolside deployment**: Run `pool login --api-url <api-url>`, then reconnect.
* **Missing mode, history, rewind, or slash command support**: ACP capabilities depend on both your editor client and your Poolside account access. The same `pool acp` server can expose a capability that an editor does not show in its UI.

After fixing authentication or configuration, reconnect the editor integration or restart the editor session.

## Related resources

* [Install Poolside Agent CLI](/cli/install)
* [Interactive mode](/cli/interactive-mode)
* [Editor integration (ACP)](/cli/editor-integration)
* [CLI reference](/cli/cli-reference)