Troubleshooting Guide

Fresh 🌱

Common problems and their solutions.

Installation Issues

Problem: pip: command not found

Solution:

# Use python -m pip
python -m pip install fastapi-poe

# Or install pip
python -m ensurepip --upgrade

Problem: Permission denied during install

Solution:

# Install for user only
pip install --user fastapi-poe

# Or use virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
pip install fastapi-poe

Problem: Import error after installation

Solution:

# Verify installation
pip show fastapi-poe

# Reinstall
pip uninstall fastapi-poe
pip install fastapi-poe

# Check Python path
python -c "import sys; print(sys.path)"

API Key Issues

Problem: Invalid API key

Symptoms:

• Error: "Invalid API key" or "Authentication failed"

Solutions:

1. Verify API key is correct:

   import os
   api_key = os.getenv("POE_API_KEY")
   print(f"Key length: {len(api_key) if api_key else 0}")

2. Check for extra spaces:

   api_key = api_key.strip()  # Remove whitespace

3. Verify environment variable is set:

   # Windows PowerShell
   echo $env:POE_API_KEY
   
   # Linux/Mac
   echo $POE_API_KEY

4. Get a new API key from poe.com/api_key

Problem: API key not found

Solutions:

1. Check .env file exists and is loaded:

   from dotenv import load_dotenv
   load_dotenv()  # Must call this

2. Verify .env file format:

   POE_API_KEY=your_key_here  # No spaces around =

3. Use absolute path:

   from dotenv import load_dotenv
   from pathlib import Path
   load_dotenv(Path(__file__).parent / ".env")

Query Issues

Problem: Bot not found

Symptoms:

• Error: "Bot not found" or "Invalid bot name"

Solutions:

1. Check bot name spelling (case-sensitive):

   # Correct
   bot_name = "GPT-5"
   bot_name = "Claude-Sonnet-4.5"
   
   # Incorrect
   bot_name = "gpt-5"  # Wrong case
   bot_name = "GPT5"   # Missing hyphen

2. Verify bot is available:

   • Check Poe website for available bots
   • Try a different bot name

3. Common bot names:

   • GPT-5
   • Claude-Sonnet-4.5
   • Claude-Opus-4.1
   • Grok-4
   • Imagen-4

Problem: Rate limit exceeded

Symptoms:

• Error: "Rate limit exceeded" or "Too many requests"

Solutions:

1. Wait 60 seconds before retrying

2. Implement rate limiting:

   import time
   from collections import deque
   
   class RateLimiter:
       def __init__(self, max_requests=500, window=60):
           self.max_requests = max_requests
           self.window = window
           self.requests = deque()
       
       async def wait_if_needed(self):
           now = time.time()
           while self.requests and self.requests[0] < now - self.window:
               self.requests.popleft()
           
           if len(self.requests) >= self.max_requests:
               sleep_time = self.window - (now - self.requests[0])
               await asyncio.sleep(sleep_time)
           
           self.requests.append(time.time())

3. Reduce request frequency

4. Use async with delays between requests

Problem: Insufficient points

Symptoms:

• Error: "Insufficient points" or "Not enough credits"

Solutions:

1. Check your Poe account balance
2. Purchase more points if needed
3. Use bots that consume fewer points
4. Reduce thinking budget or reasoning effort

Problem: Timeout errors

Symptoms:

• Request hangs or times out

Solutions:

1. Increase timeout:

   # For OpenAI-compatible API
   client = OpenAI(
       api_key=api_key,
       base_url="https://api.poe.com/v1",
       timeout=60.0  # 60 seconds
   )

2. Use async with proper error handling:

   import asyncio
   
   async def query_with_timeout():
       try:
           async with asyncio.timeout(60):
               # Your query here
               pass
       except asyncio.TimeoutError:
           print("Request timed out")

3. Check internet connection

4. Retry with exponential backoff

File Upload Issues

Problem: File not found

Solutions:

1. Use absolute path:

   from pathlib import Path
   file_path = Path(__file__).parent / "document.pdf"

2. Verify file exists:

   import os
   if not os.path.exists("document.pdf"):
       print("File not found!")

3. Check file permissions

Problem: File too large

Solutions:

1. Check file size:

   file_size = os.path.getsize("document.pdf")
   print(f"File size: {file_size / 1024 / 1024:.2f} MB")

2. Compress or split large files

3. Use smaller test file first

Problem: Unsupported file type

Solutions:

1. Use supported formats:

   • PDF (.pdf)
   • Images (.png, .jpg, .jpeg)
   • Text (.txt, .md)

2. Convert to supported format

3. Check bot's file capabilities

Parameter Issues

Problem: Parameters not working

Symptoms:

• Parameters seem to be ignored

Solutions:

1. Verify parameter format:

   # Correct
   message = fp.ProtocolMessage(
       role="user",
       content="Question",
       parameters={"thinking_budget": 12288}  # In parameters dict
   )
   
   # Incorrect
   message = fp.ProtocolMessage(
       role="user",
       content="Question --thinking_budget 12288"  # Won't work!
   )

2. Check bot supports parameter:

   • thinking_budget for Claude models
   • reasoning_effort for GPT models
   • aspect_ratio for image bots

3. Verify parameter values:

   # thinking_budget: integer
   parameters={"thinking_budget": 12288}
   
   # reasoning_effort: string
   parameters={"reasoning_effort": "high"}
   
   # aspect_ratio: string
   parameters={"aspect_ratio": "16:9"}

Network Issues

Problem: Connection errors

Solutions:

1. Check internet connection

2. Verify API endpoint is accessible:

   import requests
   response = requests.get("https://api.poe.com/v1")
   print(response.status_code)

3. Check firewall/proxy settings

4. Try from different network

Problem: SSL certificate errors

Solutions:

1. Update certificates:

   pip install --upgrade certifi

2. Update Python and pip

3. Check system date/time is correct

Debugging Tips

Enable verbose logging

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

# Your code here
logger.debug(f"Querying bot: {bot_name}")

Print request details

print(f"API Key: {api_key[:10]}...")
print(f"Bot: {bot_name}")
print(f"Message: {message.content}")
print(f"Parameters: {message.parameters}")

Test with simple query

# Minimal test
import fastapi_poe as fp
import os

api_key = os.getenv("POE_API_KEY")
message = fp.ProtocolMessage(role="user", content="Hi")

try:
    for partial in fp.get_bot_response_sync(
        messages=[message],
        bot_name="GPT-5",
        api_key=api_key
    ):
        print(partial, end="", flush=True)
    print("\n✓ Success!")
except Exception as e:
    print(f"\n✗ Error: {e}")

Getting Help

If you're still stuck:

1. Check error message - Often contains helpful details
2. Review documentation - SOPs and Workflows
3. Test with minimal example - Isolate the problem
4. Check Poe status - API might be down
5. Contact support - For API-specific issues

Common Error Messages

Error	Cause	Solution
Invalid API key	Wrong or missing key	Verify API key
Bot not found	Wrong bot name	Check spelling
Rate limit exceeded	Too many requests	Wait 60 seconds
Insufficient points	Low balance	Add points
File not found	Wrong path	Use absolute path
Timeout	Network issue	Check connection

---

Back to: Quick Reference