Troubleshooting Guide

Comprehensive guide to diagnosing and fixing common issues with CorpusIQ.

Quick Diagnostics
Installation Issues
Server Issues
Connection Issues
Search Issues
Connector Issues
Authentication Issues
Performance Issues
Widget Issues
Configuration Issues
Debugging Tips

Quick Diagnostics

Before diving deep, try these quick checks:

Health Check Script

# Run this diagnostic script
cd corpusiq-openai-sdk

# Check Python version
python --version

# Check if server starts
timeout 5 python -m corpusiq || echo "Server failed to start"

# Check endpoints (if running)
curl http://localhost:8000/ || echo "Server not responding"
curl http://localhost:8000/.well-known/oauth-protected-resource || echo "OAuth endpoint issue"

Common Quick Fixes

Restart the server: Stop (Ctrl+C) and restart (python -m corpusiq)
Check virtual environment: Ensure it’s activated
Reinstall dependencies: pip install -e . --force-reinstall
Check logs: Look for error messages in terminal output
Clear cache: rm -rf __pycache__ in src directories

Installation Issues

Error: `ModuleNotFoundError: No module named 'corpusiq'`

Cause: Package not installed or virtual environment not activated.

Solutions:

# Verify virtual environment is activated
which python
# Should show path to .venv/bin/python

# If not activated:
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate     # Windows

# Reinstall package
pip install -e .

Error: `Python version not supported`

Cause: Python version is older than 3.10.

Solutions:

# Check Python version
python --version

# If too old, install Python 3.10+:
# macOS:
brew install python@3.11

# Ubuntu/Debian:
sudo apt install python3.11

# Then recreate virtual environment:
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

Error: `pip: command not found`

Cause: pip not installed or not in PATH.

Solutions:

# Install pip:
python -m ensurepip --upgrade

# Or install Python with pip:
# macOS:
brew install python@3.11

# Ubuntu/Debian:
sudo apt install python3-pip

Error: `Permission denied` during installation

Cause: Trying to install system-wide without permissions.

Solutions:

# Don't use sudo with virtual environments!
# Instead, use virtual environment:
python -m venv .venv
source .venv/bin/activate
pip install -e .

# If you must install system-wide (not recommended):
pip install --user -e .

Dependencies fail to install

Cause: Network issues, outdated pip, or conflicting packages.

Solutions:

# Upgrade pip first
pip install --upgrade pip setuptools wheel

# Try installing again
pip install -e .

# If still failing, install individually:
pip install fastapi uvicorn pydantic mcp

# Check for conflicts:
pip check

Server Issues

Server won’t start

Symptoms: Error immediately when running python -m corpusiq.

Diagnostic steps:

# 1. Check if port 8000 is already in use
lsof -i :8000  # macOS/Linux
netstat -ano | findstr :8000  # Windows

# 2. Try a different port
CORPUSIQ_PORT=8001 python -m corpusiq

# 3. Check environment variables
cat .env

# 4. Run in debug mode
CORPUSIQ_DEBUG_MODE=true python -m corpusiq

Common causes & solutions:

Port already in use:

# Kill existing process
kill -9 $(lsof -t -i:8000)  # macOS/Linux
# Or use a different port

Invalid .env file:

# Validate .env syntax
cat .env
# Ensure no spaces around = signs
CORRECT=value
# Not: WRONG = value

Missing assets:

# Check if widget exists
ls assets/corpusiq.html
# If missing, restore:
git checkout assets/

Server crashes immediately

Symptoms: Server starts then crashes with error.

Diagnostic:

# Run with full logging
CORPUSIQ_LOG_LEVEL=DEBUG python -m corpusiq 2>&1 | tee server.log

# Check the last error in log
tail -50 server.log

Common issues:

Import errors: Reinstall dependencies
Configuration errors: Check .env file
File permissions: Ensure read access to all files
Memory issues: Check available RAM

Server runs but responds slowly

Symptoms: Server takes >5 seconds to respond.

Diagnostic:

# Check response time
time curl http://localhost:8000/

# Check server logs for slow operations
CORPUSIQ_LOG_LEVEL=DEBUG python -m corpusiq

Solutions:

Increase resources: More RAM/CPU
Reduce load: Lower rate limits
Optimize queries: Cache frequently accessed data
Check network: Ensure fast connection to data sources

Connection Issues

ChatGPT can’t connect to server

Symptoms: “Unable to reach server” or timeout errors in ChatGPT.

Step-by-step diagnosis:

# 1. Verify server is running
curl http://localhost:8000/
# Should return: {"status": "ok", ...}

# 2. Verify tunnel is working
# Visit the tunnel URL in browser
open https://your-tunnel-url.com

# 3. Check CORS configuration
curl -H "Origin: https://chat.openai.com" \
     -H "Access-Control-Request-Method: POST" \
     -H "Access-Control-Request-Headers: Content-Type" \
     -X OPTIONS \
     https://your-tunnel-url.com/mcp

# Should include CORS headers in response

Common causes:

Server not running:

ps aux | grep corpusiq
# If no output, start server
python -m corpusiq

Tunnel not active:

# Restart tunnel
cloudflared tunnel --url http://localhost:8000
# or
ngrok http 8000

Wrong URL in ChatGPT:
- Must be HTTPS (not HTTP)
- Must match tunnel URL exactly
- No trailing slash

CORS not configured:

# In .env, ensure:
CORPUSIQ_CORS_ALLOW_ORIGINS_CSV=https://chat.openai.com

# Restart server after changes

Firewall blocking:
- Check firewall allows outbound HTTPS
- Check tunnel service isn’t blocked
- Try different network

Tunnel keeps disconnecting

Symptoms: Connection works briefly then fails.

Solutions:

Cloudflare Tunnel:

# Use authenticated tunnel (more stable)
cloudflared tunnel login
cloudflared tunnel create corpusiq
cloudflared tunnel route dns corpusiq your-subdomain.yourdomain.com
cloudflared tunnel run corpusiq --url http://localhost:8000

ngrok:

# Use authenticated ngrok (more stable)
ngrok authtoken YOUR_TOKEN
ngrok http 8000

Alternative: Deploy to cloud platform for stable URL

SSL/TLS errors

Symptoms: “Certificate error” or “SSL handshake failed”.

Solutions:

Tunnel-provided HTTPS: Use tunnel’s HTTPS URL (handles SSL for you)

Custom domain: Ensure valid SSL certificate

# Check certificate
openssl s_client -connect your-domain.com:443

Let’s Encrypt: Use certbot for free SSL

certbot certonly --standalone -d your-domain.com

Search Issues

Search returns no results

Diagnostics:

# 1. Check if connectors are truly connected
curl http://localhost:8000/debug/tools
# (requires DEBUG_MODE=true)

# 2. Test search directly
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "corpus_search",
      "arguments": {"query": "test", "maxResults": 5}
    }
  }'

Common causes:

No connectors connected:
- Open connectors interface
- Verify status shows “Connected” (green)
- Reconnect if needed
Empty data sources:
- Verify data exists in connected sources
- Check date ranges (some sources need recent data)
OAuth tokens expired:
- Disconnect and reconnect connector
- Reauthenticate with OAuth
Query too specific:
- Try broader search terms
- Remove date/time constraints
- Search fewer terms
API rate limits:
- Wait a few minutes
- Check data source API status

Search returns irrelevant results

Solutions:

Be more specific:

# Instead of: "report"
# Try: "Q4 financial report 2024"

Use exact phrases:

# Use quotes: "project phoenix status update"

Exclude terms:
```
# Use minus: "budget -draft"
```

Specify source:

# "Search my Gmail for..."
# "Find in my Drive..."

Search is slow

Symptoms: Takes >5 seconds to return results.

Causes & solutions:

Many connectors: More sources = more time
- Disable unused connectors
- Search specific sources
Large result sets:
- Reduce maxResults
- Be more specific in query
Slow data source APIs:
- Check API status pages
- Try again during off-peak hours
Server resources:
- Upgrade server RAM/CPU
- Use faster hosting

Connector Issues

Can’t add connector

Symptoms: Connector addition fails or hangs.

Diagnostics:

# Check OAuth endpoints
curl http://localhost:8000/.well-known/oauth-authorization-server

# Check logs during connection attempt
tail -f server.log

Solutions:

OAuth misconfigured:
- Verify OAuth provider settings in .env
- Check callback URLs match
- Ensure OAuth app is active
Popup blocked:
- Allow popups for ChatGPT domain
- Try different browser
Network issues:
- Check internet connection
- Verify firewall allows OAuth redirects

Connector shows “Error” status

Symptoms: Red error indicator on connector.

Steps to fix:

# 1. Check server logs
grep -i error server.log

# 2. Check API credentials
# Verify OAuth tokens are valid

# 3. Test API directly
# (depends on connector type)

Common fixes:

Expired token:
- Disconnect connector
- Reconnect to reauthenticate
API quota exceeded:
- Wait for quota reset
- Check API dashboard
Permission revoked:
- Check data source settings
- Ensure CorpusIQ still has access
Service outage:
- Check service status page
- Wait for service to recover

Connector shows “Connecting” forever

Symptoms: Yellow status never changes to green.

Solutions:

Refresh page: Sometimes status doesn’t update
Check OAuth callback: Ensure redirect succeeded
Review logs: Look for errors during connection
Reconnect: Remove and re-add connector

Authentication Issues

401 Unauthorized errors

Symptoms: All requests return 401.

Causes:

Production mode without OAuth:

# For testing, disable auth:
CORPUSIQ_DEBUG_MODE=true

# For production, implement OAuth
# See DEPLOYMENT.md

Invalid token:
- Check token format
- Verify token hasn’t expired
- Validate with OAuth provider

Wrong authorization header:

# Correct format:
Authorization: Bearer your-token-here

# Not: Authorization: your-token-here

OAuth flow fails

Symptoms: Redirect doesn’t work or shows error.

Diagnostics:

# Check OAuth configuration
cat .env | grep OAUTH

# Test OAuth endpoints
curl http://localhost:8000/.well-known/oauth-authorization-server
curl http://localhost:8000/.well-known/oauth-protected-resource

Solutions:

Callback URL mismatch:
- Update OAuth app settings
- Match exactly with ChatGPT callback
Invalid OAuth provider:
- Verify provider URLs are accessible
- Check provider is operational
Scope issues:
- Ensure required scopes are enabled
- Check user has permissions

Performance Issues

High CPU usage

Diagnostics:

# Check CPU usage
top -p $(pgrep -f corpusiq)

# Profile the application
python -m cProfile -m corpusiq > profile.txt

Solutions:

Too many requests: Implement rate limiting
Inefficient queries: Optimize data source calls
Memory leaks: Restart server, update code
Upgrade resources: More CPU cores

High memory usage

Diagnostics:

# Check memory
ps aux | grep corpusiq

# Monitor over time
watch -n 5 'ps aux | grep corpusiq'

Solutions:

Large result sets: Reduce maxResults
Caching issues: Clear cache, restart server
Memory leak: Update to latest version
Upgrade RAM: Add more memory

Rate limit errors (429)

Symptoms: “Rate limit exceeded” errors.

Solutions:

# Increase rate limit in .env
CORPUSIQ_RATE_LIMIT_REQUESTS_PER_MINUTE=120

# Or wait 60 seconds before retry

# For high-traffic deployments, use Redis:
# See DEPLOYMENT.md for Redis rate limiting

Diagnostics:

# Check if HTML file exists
ls -la assets/corpusiq.html

# Check file contents
head assets/corpusiq.html

# Check server logs for widget loading
grep widget server.log

Solutions:

Missing file:
```
git checkout assets/corpusiq.html
```
File permissions:
```
chmod 644 assets/corpusiq.html
```
CORS issue:
- Check CORS headers in response
- Verify origin is allowed
Browser console errors:
- Open browser dev tools
- Check console for errors
- Check network tab for failed requests

Solutions:

JavaScript errors:
- Check browser console
- Clear browser cache
- Try different browser
CORS blocking requests:
- Verify CORS allows POST requests
- Check preflight OPTIONS requests succeed
Widget version mismatch:
- Pull latest code
- Clear cache
- Restart server

Configuration Issues

Environment variables not working

Symptoms: Changes to .env have no effect.

Common mistakes:

# ❌ Wrong: spaces around =
KEY = value

# ✅ Correct: no spaces
KEY=value

# ❌ Wrong: quotes around everything
KEY="value"

# ✅ Correct: only if value has spaces
KEY=value with spaces needs quotes
KEY="value with spaces"

# ❌ Wrong: not restarting server
# ✅ Correct: always restart after .env changes

Verification:

# Check if variables are loaded
python -c "from corpusiq.settings import Settings; print(Settings())"

CORS not working

Symptoms: Browser shows CORS errors.

Fix:

# In .env:
CORPUSIQ_CORS_ALLOW_ORIGINS_CSV=https://chat.openai.com

# For testing multiple origins:
CORPUSIQ_CORS_ALLOW_ORIGINS_CSV=https://chat.openai.com,https://other-domain.com

# Restart server

Verify:

curl -H "Origin: https://chat.openai.com" \
     -H "Access-Control-Request-Method: POST" \
     -X OPTIONS \
     http://localhost:8000/mcp

# Should show Access-Control-Allow-Origin header

Debugging Tips

Enable debug logging

# In .env:
CORPUSIQ_DEBUG_MODE=true
CORPUSIQ_LOG_LEVEL=DEBUG

# Restart server
python -m corpusiq

# Or run with environment variable:
CORPUSIQ_LOG_LEVEL=DEBUG python -m corpusiq

Capture full logs

# Redirect output to file
python -m corpusiq 2>&1 | tee server.log

# View logs in real-time
tail -f server.log

# Search logs
grep -i error server.log
grep -i warning server.log

Test individual components

# Test Python imports
python -c "from corpusiq import app; print('OK')"

# Test MCP server
python -c "from corpusiq.mcp_server import _load_widget_html; print('OK')"

# Test settings
python -c "from corpusiq.settings import Settings; s = Settings(); print(s)"

Network debugging

# Test local server
curl -v http://localhost:8000/

# Test through tunnel
curl -v https://your-tunnel-url.com/

# Test MCP endpoint
curl -v -X POST https://your-tunnel-url.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list"}'

Browser debugging

Open Developer Tools (F12)
Check Console tab for errors
Check Network tab for failed requests
Check Application tab for storage issues

Getting Help

If you’ve tried everything and still have issues:

Check existing issues: https://github.com/CorpusIQ/corpusiq-openai-sdk/issues
Create a new issue with:
- Clear problem description
- Steps to reproduce
- Environment details (OS, Python version, etc.)
- Relevant log excerpts
- What you’ve already tried
Ask in Discussions: https://github.com/CorpusIQ/corpusiq-openai-sdk/discussions

Troubleshooting Guide

Table of Contents

Quick Diagnostics

Health Check Script

Common Quick Fixes

Installation Issues

Error: ModuleNotFoundError: No module named 'corpusiq'

Error: Python version not supported

Error: pip: command not found

Error: Permission denied during installation

Dependencies fail to install

Server Issues

Server won’t start

Server crashes immediately

Server runs but responds slowly

Connection Issues

ChatGPT can’t connect to server

Tunnel keeps disconnecting

SSL/TLS errors

Search Issues

Search returns no results

Search returns irrelevant results

Search is slow

Connector Issues

Can’t add connector

Connector shows “Error” status

Connector shows “Connecting” forever

Authentication Issues

401 Unauthorized errors

OAuth flow fails

Performance Issues

High CPU usage

High memory usage

Rate limit errors (429)

Widget Issues

Widget doesn’t display

Widget loads but buttons don’t work

Configuration Issues

Environment variables not working

CORS not working

Debugging Tips

Enable debug logging

Capture full logs

Test individual components

Network debugging

Browser debugging

Getting Help

Still Stuck?

Error: `ModuleNotFoundError: No module named 'corpusiq'`

Error: `Python version not supported`

Error: `pip: command not found`

Error: `Permission denied` during installation