> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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 shell troubleshooting commands in your terminal, not inside the interactive `pool` prompt or an editor chat panel. Use slash commands such as `/logs` inside an interactive `pool` session. To leave an interactive `pool` session, type `/quit` or press `Ctrl+C` twice.
This documentation describes Poolside Agent CLI v1.0.15. Check your version with `pool --version`. To update, exit any active session and run `pool update` from your terminal. See [Poolside Agent CLI releases on GitHub](https://github.com/poolsideai/pool/releases) for release history.
## 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.
1. Check whether authentication environment variables are set.
```bash theme={null}
env | grep -E '^POOLSIDE_(API_KEY|API_URL|TOKEN|STANDALONE_BASE_URL|STANDALONE_CONTEXT_LENGTH|STANDALONE_MODEL)=' | sed 's/=.*/=/'
```
This command shows whether a variable is set without printing the secret value.
2. Confirm that `pool` is using the connection variables for your access method:
* For Poolside-hosted inference, self-managed Poolside inference, an inference gateway, or another OpenAI-compatible endpoint, set `POOLSIDE_STANDALONE_BASE_URL` and `POOLSIDE_API_KEY`. If your endpoint does not list models from its API, also set `POOLSIDE_STANDALONE_MODEL`.
If you used `pool login`, check the saved configuration instead. For setup details, see [Install and authenticate](/cli/install#install-and-authenticate).
3. If any variables do not match your intended connection, test without the environment overrides.
```bash theme={null}
env -u POOLSIDE_API_KEY -u POOLSIDE_API_URL -u POOLSIDE_TOKEN -u POOLSIDE_STANDALONE_BASE_URL -u POOLSIDE_STANDALONE_CONTEXT_LENGTH -u POOLSIDE_STANDALONE_MODEL pool
```
4. Sign in again.
```bash theme={null}
pool logout
pool login
```
5. Choose the sign-in method that matches your setup. For details, see [Install and authenticate](/cli/install#install-and-authenticate).
6. 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.
## Fix connection errors in automation
If `pool exec` returns `agent not found` or `user is not authorized to use --unsafe-auto-allow` when you intend to use Poolside-hosted inference, set the standalone endpoint variable:
```bash theme={null}
POOLSIDE_API_KEY= \
POOLSIDE_STANDALONE_BASE_URL=https://inference.poolside.ai \
pool exec -p "" --unsafe-auto-allow
```
To choose a model instead of using the default, also set `POOLSIDE_STANDALONE_MODEL` to its model ID.
## 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.
## Fix clipboard errors on Linux
Clipboard support depends on your display server:
* On Wayland, install the `wl-clipboard` package so `wl-copy` and `wl-paste` are available.
* On X11, install `xclip` for text, image, and file clipboard support. You can use `xsel` instead if you only need text clipboard support.
Restart `pool` after installing the required commands.
## Collect interactive session logs
Use this section when an interactive `pool` session shows an error or asks you to collect logs.
1. In the interactive `pool` prompt, type:
```text theme={null}
/logs
```
2. Review the generated `logs.zip` archive before sharing it.
The archive can include session logs, ACP logs, trajectory data, and session metadata. Logs and trajectory data can include prompt and response text from the session.
## 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 with Poolside-hosted inference, self-managed Poolside inference, OpenRouter, or another OpenAI-compatible endpoint**: Run `pool login`, choose the matching login option, enter the required credentials, 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)
* [CLI reference](/cli/cli-reference)