Skip to main content
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.16. 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:
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.
  1. Check whether authentication environment variables are set.
    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.
  3. If any variables do not match your intended connection, test without the environment overrides.
  4. Sign in again.
  5. Choose the sign-in method that matches your setup. For details, see Install and authenticate.
  6. Start a new session and send a short text prompt.
    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:
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:
  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:
For formatted logs, run:
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.