Troubleshoot Poolside Agent CLI - Poolside

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

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.13. 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 for release history.

Check which files Poolside uses

Run:

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.

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.

Check whether authentication environment variables are set.

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.

If you intentionally use a local OpenAI-compatible model server, confirm that pool is using the base URL, API key, and model you expect. If you used pool login, check the saved configuration. If you use environment variables instead, set POOLSIDE_STANDALONE_BASE_URL and POOLSIDE_API_KEY in the shell that starts pool. If your server does not list models from its API, also set POOLSIDE_STANDALONE_MODEL. For setup details, see Install and authenticate.
If any of those variables are set and you are not using a local OpenAI-compatible model server, test without them.

env -u POOLSIDE_API_KEY -u POOLSIDE_TOKEN -u POOLSIDE_STANDALONE_BASE_URL -u POOLSIDE_STANDALONE_MODEL pool

pool logout
pool login

Choose the sign-in method that matches your setup. For details, see Install and authenticate. If you already know the Poolside deployment URL, you can sign in directly:

pool login --api-url <api-url>

Start a new session and send a short text prompt.

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.

Collect interactive session logs

Use this section when an interactive pool session shows an error or asks you to collect logs.

In the interactive pool prompt, type:

/logs

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:

pool acp logs -f

For formatted logs, run:

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 Platform, OpenRouter, or an OpenAI-compatible provider: Run pool login, choose the matching login option, enter the required credentials, 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.