Skip to main content

Troubleshooting Guide

Common issues and solutions for PolyOracle AI setup and operation.

Installation Issues​

Backend Installation Problems​

Python Version Issues

Error: Python 3.11+ required, found 3.9

Solution:

  • Install Python 3.11+ from python.org
  • Use pyenv: pyenv install 3.11.0 && pyenv global 3.11.0
  • Verify version: python --version

Package Installation Failures

Error: Failed building wheel for some-package

Solutions:

  1. Update pip: pip install --upgrade pip
  2. Install build tools: pip install wheel setuptools
  3. Try alternative install: pdm install
  4. On Mac: xcode-select --install

LangGraph Import Errors

ImportError: No module named 'langgraph'

Solution:

pip install -e ".[dev]"
# Or
pip install langgraph langchain-openai

Frontend Installation Problems​

Node.js Version Issues

Error: Node.js 18+ required

Solutions:

  • Install Node.js 18+ from nodejs.org
  • Use nvm: nvm install 18 && nvm use 18
  • Verify: node --version

pnpm Not Found

Command 'pnpm' not found

Solutions:

npm install -g pnpm
# Or use npx
npx pnpm install

Next.js Build Errors

Error: Cannot resolve module '@/components/...'

Solution:

  • Check tsconfig.json paths configuration
  • Verify component file exists
  • Restart development server: pnpm dev

API Configuration Issues​

OpenAI API Problems​

Invalid API Key

Error: Incorrect API key provided

Solutions:

  1. Verify key format starts with sk-
  2. Check for extra spaces or newlines
  3. Generate new key at platform.openai.com
  4. Ensure key has sufficient credits

Rate Limit Exceeded

Error: Rate limit reached for requests

Solutions:

  1. Reduce research depth temporarily
  2. Add delays between requests
  3. Upgrade OpenAI plan if needed
  4. Use Anthropic as backup LLM

Exa API Issues​

Search Fails

Error: EXA_API_KEY not configured

Solutions:

  1. Get API key from exa.ai
  2. Add to .env: EXA_API_KEY=your_key
  3. Restart backend server
  4. Verify with test search

Search Results Empty

Warning: No search results found

Solutions:

  1. Try broader search terms
  2. Check internet connectivity
  3. Verify Exa API has credits
  4. Use Tavily as backup search

Polymarket API Problems​

Connection Failed

Error: Failed to connect to Polymarket API

Solutions:

  1. Verify API key and secret in .env
  2. Check network connectivity
  3. Confirm API keys have trading permissions
  4. Try API endpoint manually: curl https://clob.polymarket.com/ping

Proxy Contract Issues

Error: Proxy contract not found

Solutions:

  1. Create proxy contract on polymarket.com
  2. Copy correct proxy address to .env
  3. Verify proxy is on Polygon network
  4. Check wallet has approved proxy

Runtime Errors​

Backend Runtime Issues​

LangGraph Server Won't Start

Error: Port 2024 already in use

Solutions:

# Kill existing process
lsof -ti:2024 | xargs kill -9
# Or use different port
langgraph dev --port 2025

Memory Errors

Error: Out of memory

Solutions:

  1. Reduce research depth: max_depth: 2
  2. Limit concurrent requests
  3. Increase system memory
  4. Use smaller LLM model

Timeout Errors

Error: Request timeout after 300s

Solutions:

  1. Increase timeout in configuration
  2. Check internet connection stability
  3. Use faster LLM model
  4. Reduce research scope

Frontend Runtime Issues​

Wallet Connection Failed

Error: No Web3 provider found

Solutions:

  1. Install MetaMask or similar wallet
  2. Enable browser extension
  3. Switch to Polygon network
  4. Refresh page and retry

API Connection Failed

Error: Cannot connect to backend

Solutions:

  1. Verify backend is running on correct port
  2. Check LANGGRAPH_DEPLOYMENT_URL in .env.local
  3. Test backend health: curl http://localhost:2024/health
  4. Check firewall/network settings

Trading Issues​

Order Execution Problems​

Insufficient Balance

Error: Insufficient USDC balance

Solutions:

  1. Check wallet USDC balance
  2. Ensure funds are on Polygon network
  3. Account for gas fees (need MATIC)
  4. Verify proxy contract has approvals

Order Rejected

Error: Order rejected by exchange

Solutions:

  1. Check market is still active
  2. Verify order size within limits
  3. Check current market price hasn't moved
  4. Ensure sufficient liquidity

Gas Estimation Failed

Error: Cannot estimate gas

Solutions:

  1. Ensure wallet has MATIC for gas
  2. Check Polygon network status
  3. Try smaller order size
  4. Wait and retry (network congestion)

Position Management Issues​

Position Not Found

Error: No position found for market

Solutions:

  1. Check if tokens were received
  2. Verify correct market ID
  3. Allow time for blockchain confirmation
  4. Check wallet transaction history

P&L Calculation Wrong

Warning: Unrealized P&L seems incorrect

Solutions:

  1. Refresh market data
  2. Check if market resolved
  3. Verify position size calculation
  4. Account for trading fees

Performance Issues​

Slow Analysis​

Research Takes Too Long

Warning: Research phase taking over 10 minutes

Solutions:

  1. Reduce research depth: max_depth: 2
  2. Limit sources per query: sources_per_query: 5
  3. Check internet speed
  4. Use cached research when available

Memory Usage High

Warning: High memory usage detected

Solutions:

  1. Restart backend service periodically
  2. Reduce concurrent analysis
  3. Clear research cache
  4. Monitor system resources

Network Issues​

Intermittent Connectivity

Error: Connection lost during analysis

Solutions:

  1. Implement retry logic
  2. Save analysis state periodically
  3. Use more stable internet connection
  4. Consider VPN for stability

Data Issues​

Market Data Problems​

Stale Market Data

Warning: Market data is over 1 hour old

Solutions:

  1. Refresh market data manually
  2. Check Polymarket API status
  3. Verify internet connectivity
  4. Use cached data as fallback

Missing Market Information

Error: Market not found or delisted

Solutions:

  1. Verify market ID is correct
  2. Check if market was delisted
  3. Use alternative similar markets
  4. Update market list

Security Issues​

API Key Exposure​

Key Visible in Logs

Warning: API key detected in log output

Solutions:

  1. Check environment variable loading
  2. Verify .env file permissions: chmod 600 .env
  3. Review log configuration
  4. Rotate exposed keys immediately

Suspicious Activity

Alert: Unusual API usage detected

Solutions:

  1. Review recent trading activity
  2. Check API key usage in provider dashboard
  3. Rotate API keys if compromised
  4. Enable 2FA on all accounts

Getting Additional Help​

Log Analysis​

Enable Debug Logging:

# Backend
export LOG_LEVEL=DEBUG
make lg-server

# Frontend  
export NODE_ENV=development
pnpm dev

Important Log Locations:

  • Backend: Terminal output + logs/ directory
  • Frontend: Browser console + Network tab
  • Blockchain: Wallet transaction history

Diagnostic Commands​

Backend Health Check:

curl http://localhost:2024/health
python -c "import langgraph; print('OK')"

Frontend Health Check:

pnpm lint
pnpm build --dry-run

Network Connectivity:

curl -I https://api.openai.com
curl -I https://search.exa.ai
curl -I https://clob.polymarket.com/ping

Community Support​

Report Issues:

  • GitHub Issues: Include error messages and system info
  • Discord: Real-time community help
  • Documentation: Check FAQ for common issues

Provide System Information:

python --version
node --version
pnpm --version
uname -a  # or systeminfo on Windows

Include Relevant Logs:

  • Sanitize API keys and private information
  • Include error context (before/after error)
  • Specify exact steps to reproduce issue

Preventive Measures​

Regular Maintenance​

Weekly Tasks:

  • Update dependencies: pip install --upgrade -r requirements.txt
  • Rotate API keys if high-volume usage
  • Review trading performance and adjust parameters
  • Check for software updates

Monthly Tasks:

  • Full system backup including configurations
  • Review and optimize risk management settings
  • Analyze trading patterns for improvements
  • Update documentation for any workflow changes

Monitoring Setup​

Automated Monitoring:

# Add to your monitoring script
health_checks = [
    "backend_health",
    "frontend_health", 
    "api_connectivity",
    "wallet_balance",
    "recent_trades"
]

Alerts Configuration:

  • Low wallet balance warnings
  • API quota approaching limits
  • Unusual trading patterns
  • System performance degradation

Still having issues? Check the FAQ or create an issue on GitHub with detailed error information.