Troubleshooting

Common issues and solutions when working with ACP. Each section covers a specific problem category with diagnostic steps and fixes.

Quick navigation

1. Import Errors

ModuleNotFoundError: No module named 'acp'

Cause: The project is not installed as a package. Some documentation may incorrectly show from acp import.

Solution: Use correct imports from the project root:

Correct imports

# Correct
from src.engine import ConsensusEngine, ConsensusConfig
from src.llm.openrouter_llm import OpenRouterLLM

# Incorrect (outdated documentation)
# from acp import ConsensusEngine

ModuleNotFoundError: No module named 'src'

Cause: Running scripts from the wrong directory.

Solution: Always run from the project root:

Verify and fix working directory

# Check current directory
pwd
# Should output: /path/to/ACP-PROJECT

# Verify project structure
ls -la
# Should show: src/, examples/, workers/, archive/

# If not in project root, navigate there
cd /path/to/ACP-PROJECT
python examples/01_simple_query.py

Dependencies not found (openai, anthropic, httpx)

Solution: Create a fresh virtual environment and install dependencies:

Clean dependency installation

# Create fresh virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

# Verify installation
pip list | grep -E "(openai|anthropic|httpx)"

2. API Connection Issues

404 Not Found on /consensus endpoint

Cause: Using an incorrect endpoint or base URL. The Worker API and Python API use different endpoint paths.

Solution -- Worker API (production):

Correct Worker API endpoint

# Correct endpoint
curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-openrouter-key: YOUR_KEY" \
  -d '{"query": "test", "models": ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]}'

Solution -- Python API (local):

Correct Python API endpoint

# Start the server first
uvicorn main:app --reload --port 8000

# Use the correct endpoint
curl -X POST http://localhost:8000/consensus/sync \
  -H "Content-Type: application/json" \
  -d '{
    "query": "test",
    "models": [
      {"provider": "openrouter", "name": "gpt4", "model": "openai/gpt-5.4-mini"}
    ]
  }'

Connection refused or timeout

Diagnostic steps:

Check service availability

# Check Worker (production)
curl https://your-worker.workers.dev/health

# Check Python API (local)
curl http://localhost:8000/health

# If Python API is not responding, check if it is running
ps aux | grep uvicorn

# If not running, start it
cd /path/to/ACP-PROJECT
uvicorn main:app --reload --port 8000

3. Authentication Problems

"Unauthorized" or "Invalid API key"

Cause: Missing or incorrect API key in the request headers.

Set and verify API key

# Get key from: https://openrouter.ai/keys
export OPENROUTER_API_KEY="sk-or-v1-YOUR_KEY_HERE"

# Use in Worker API requests
curl -H "x-openrouter-key: $OPENROUTER_API_KEY" \
  https://your-worker.workers.dev/consensus-iterative ...

# Verify key is valid
curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"
# Should return a JSON list of available models

"Rate limit exceeded"

Solution: OpenRouter enforces per-minute rate limits. To resolve:

Check your current usage at openrouter.ai/usage
Add delays between requests
Enable semantic caching (skip_cache: false) to reuse similar query results
Upgrade your OpenRouter plan for higher limits

4. Database Issues

"Database connection failed" when running frontend

Cause: PostgreSQL is not running or DATABASE_URL is not set.

Database is optional

The frontend and API work without a database when WORKER_URL is set. Comment out DATABASE_URL in your .env to skip database requirements entirely.

Quick fix: Remove the database requirement:

.env

WORKER_URL=https://your-worker.workers.dev

# Comment out to skip database:
# DATABASE_URL="postgresql://..."

Full setup (if database features are needed):

PostgreSQL setup (macOS)

brew install postgresql@15
brew services start postgresql@15

createdb acp_db

PostgreSQL setup (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

sudo systemctl start postgresql
sudo systemctl enable postgresql

sudo -u postgres createdb acp_db
sudo -u postgres createuser acp

Configure and migrate

# Set DATABASE_URL in .env
DATABASE_URL="postgresql://acp:password@localhost:5432/acp_db"

# Run migrations
npx prisma migrate dev

5. Vectorize and Axioms

"Vectorize not available" or "axioms_seeded: false"

Cause: The axiom database has not been seeded in Cloudflare Vectorize.

Diagnostic:

Check Worker health

curl https://your-worker.workers.dev/health

# Look for:
# "vectorize": {"available": true, "axioms_seeded": false}

Solution: Seed the axioms (requires Cloudflare account access):

Seed axiom database

cd workers/cloudflare-worker

# Set Cloudflare credentials
export CLOUDFLARE_API_TOKEN="your_token"
export CLOUDFLARE_ACCOUNT_ID="your_account_id"

# Run seeding script
node ../../scripts/vectorize/seed-all-axioms.js

# Verify
curl https://your-worker.workers.dev/health
# "axioms_seeded" should now be true

Production seeding

For the public production worker, axiom seeding is handled by ACP maintainers. You only need to seed axioms when running your own self-hosted worker.

6. Playground Issues

Playground shows "Coming Soon"

Cause: The playground UI may be under development for certain features.

Workarounds:

Option	Command	Access
Local Dashboard	`npm run dev`	localhost:3000/dashboard
API directly	`curl POST /consensus-iterative`	See API Connection section above
Python examples	`python examples/01_simple_query.py`	Run from project root

Demo mode not loading

Solution:

Check that all fixture JSON files are valid (use a JSON validator)
Ensure fixtures are imported in data/demo-fixtures/index.ts
Rebuild the application: npm run build
Check browser console for JavaScript errors

Live mode stuck loading

Solution:

Check the Network tab in browser DevTools for failed requests
Verify the API endpoint is reachable: curl https://your-worker.workers.dev/health
Ensure at least 2 models are selected
Check that your OpenRouter account has sufficient credits
Try reducing the number of models or max iterations

7. Performance Issues

Consensus requests timing out

Causes: Too many iterations, slow or expensive models, or overly complex queries.

Solution 1: Reduce iterations

Lower iteration count

{
  "max_iterations": 3,
  "models": ["openai/gpt-5.4-mini", "anthropic/claude-haiku-4-5"]
}

Solution 2: Use faster models

Recommended (fast)	Avoid (slow)
`openai/gpt-5.4-mini`	`openai/gpt-5.4`
`anthropic/claude-haiku-4-5`	`anthropic/claude-opus-4-6`
`google/gemini-flash-1.5`	`google/gemini-2.5-flash`

Solution 3: Increase client timeout

Increase HTTP client timeout

import httpx

# Increase to 2 minutes (default is often 30 seconds)
client = httpx.AsyncClient(timeout=120.0)

8. Cost Management

Unexpected high costs from OpenRouter

Diagnostic: Check your usage at openrouter.ai/usage and review per-model pricing at openrouter.ai/models.

Cost reduction strategies:

Use cheaper models for testing

Budget-friendly model selection

{
  "models": [
    "openai/gpt-5.4-mini",
    "anthropic/claude-haiku-4-5",
    "google/gemini-flash-1.5"
  ]
}

Reduce iterations

Most queries converge within 2-3 iterations. Setting max_iterations to 3 significantly reduces costs for simple queries.

Enable semantic caching

Enable cache

{
  "skip_cache": false
}

The semantic cache reuses results for queries that are similar (not just identical) to previously cached ones.

Cost estimates

Query Type	Estimated Cost
Simple query (2 models, 3 iterations)	$0.02-$0.05
Complex query (3 models, 7 iterations)	$0.10-$0.30
Using GPT-4/Opus instead of mini/Haiku	5-10x more expensive

9. Development Setup

Frontend npm install fails

Clean npm installation

cd archive/frontend/acp-web

# Clean install
rm -rf node_modules package-lock.json
npm install

# If still failing, clear npm cache
npm cache clean --force
npm install

# Or use specific Node version
nvm install 18.18
nvm use 18.18
npm install

Cloudflare Worker deployment fails

Debug Worker deployment

cd workers/cloudflare-worker

# Verify wrangler version
npx wrangler --version

# Login to Cloudflare
npx wrangler login

# Check account
npx wrangler whoami

# Update wrangler.toml with correct account_id, then deploy
npx wrangler deploy

Python type errors or linting errors

Fix Python linting

# Install dev dependencies
pip install -r requirements-dev.txt

# Run type checking
mypy src/ --ignore-missing-imports

# Format code
black src/
isort src/

# Lint
ruff check src/

TypeScript build errors

Solution:

Ensure Node.js 18.18 or higher: node --version
Delete node_modules and .next, then reinstall: rm -rf node_modules .next && npm install
Verify all dependencies are installed: npm install
Clear Next.js cache: rm -rf .next

10. Getting Help

Check documentation

API Reference -- endpoint documentation, authentication, error codes
Getting Started -- setup guides from quickstart to full local installation
Self-Hosting -- deployment guides for Vercel, Docker, and Node.js

Create a new issue

When reporting an issue, include the following information to help with diagnosis:

Error message -- full traceback or console output
Steps to reproduce -- the exact commands or actions that trigger the issue
Environment details -- Python version, Node version, OS
What you have tried -- solutions you have already attempted

Collect environment details

python --version
node --version
uname -a

Community

Telegram -- t.me/D_Score
Documentation -- axiomprotocol.org

Quick Diagnostic Script

Run this script to diagnose common issues automatically. Save it as diagnose.sh, make it executable with chmod +x diagnose.sh, and run it from the project root.

diagnose.sh

#!/bin/bash
echo "=== ACP Diagnostic ==="
echo ""
echo "Project Root:"
pwd
ls -la | grep -E "(src|examples|workers|frontend)" || echo "Not in project root"
echo ""
echo "Python Version:"
python --version
echo ""
echo "Dependencies:"
pip list | grep -E "(openai|anthropic|httpx|fastapi)" || echo "Dependencies not installed"
echo ""
echo "Environment:"
env | grep -E "(OPENROUTER_API_KEY|DATABASE_URL|WORKER_URL)" | sed 's/=.*/=***/'
echo ""
echo "APIs:"
curl -s https://your-worker.workers.dev/health | head -5 || echo "Worker unreachable"
curl -s http://localhost:8000/health 2>/dev/null | head -5 || echo "Local Python API not running"
echo ""
echo "=== End Diagnostic ==="

Replace the worker URL

Edit the script to replace your-worker.workers.dev with your actual Worker deployment URL before running.

Self-Hosting

Contributing