Skip to main content
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.

​
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.

​
Steps

  1. 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.
  2. If any of those variables are set, test without them. 
    env -u POOLSIDE_API_KEY -u POOLSIDE_TOKEN -u POOLSIDE_STANDALONE_BASE_URL -u POOLSIDE_STANDALONE_MODEL pool
  3. Sign in again. 
    pool logout
pool login
  4. Choose the login flow that matches your environment:
    • Log in with Poolside: Use the public standalone Poolside flow. This opens platform.poolside.ai and asks you to paste a Poolside API key.
    • 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: 
    pool login --api-url <api-url>
  5. 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.

​
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 in standalone mode: Run pool login, choose Log in with Poolside, 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.