Troubleshooting

This guide covers common issues you might encounter while using the AP3 SDK and their solutions.

Installation Issues

Python Version Mismatch

Problem: ERROR: Package requires a different Python: 3.10.0 not in '>=3.11,<3.14'

Solution:

# Check your Python version
python --version  # Should be 3.11.x or later

# Install Python 3.11 if needed
# macOS (Homebrew)
brew install [email protected]

# Ubuntu/Debian
sudo apt-get install python3.11

# Create venv with correct version
python3.11 -m venv .venv
source .venv/bin/activate

Binary Loading Errors

Problem: OSError: cannot load library 'libsanction_check_lib.dylib'

Solution:

1. Verify binaries are present:

   ls ap3operations/psi/binaries/
   # Should show: libsanction_check_lib.dylib (macOS) or libsanction_check_lib.so (Linux)
   

2. Check platform compatibility:

   # macOS
   file ap3operations/psi/binaries/libsanction_check_lib.dylib
   # Should show: Mach-O 64-bit dynamically linked shared library
   
   # Linux
   file ap3operations/psi/binaries/libsanction_check_lib.so
   # Should show: ELF 64-bit LSB shared object, x86-64
   

3. Platform mismatch: Contact [email protected] for binaries for your platform

Configuration Issues

API Key Not Found

Problem: ValueError: GOOGLE_API_KEY environment variable not set

Solution:

# 1. Create .env file
cat > .env << 'EOF'
GOOGLE_API_KEY="your-key-here"
EOF

# 2. Load it in your code
from dotenv import load_dotenv
load_dotenv()

# 3. Verify it's loaded
import os
print("Key loaded!" if os.getenv('GOOGLE_API_KEY') else "Key missing!")

Agent Connection Refused

Problem: httpx.ConnectError: [Errno 61] Connection refused

Solution:

1. Check agent is running:

   # Check if process is listening
   lsof -i :10002  # PSI Initiator
   lsof -i :10003  # PSI Receiver
   lsof -i :8080   # Host
   

2. Verify correct URL:

   import httpx
   
   try:
       response = httpx.get("http://localhost:10002/")
       print(f"Agent responding: {response.status_code}")
   except httpx.ConnectError:
       print("❌ Agent not running or wrong URL")
   

3. Check firewall:

   # macOS - allow incoming connections
   # System Settings → Network → Firewall
   
   # Linux
   sudo ufw allow 10002
   sudo ufw allow 10003
   sudo ufw allow 8080
   

PSI Protocol Issues

Error Code -1 from Rust Library

Problem: ProtocolError: Failed to process PSI message 1: error code -1

Cause: Data format mismatch between initiator and receiver.

Solution:

1. Verify hash type consistency:

   # Initiator uses "Customer" hash type, Receiver uses "Sanction" — correct in SDK
   

2. Verify sanction list format:

   # Each entry must be "Name,ID,Address" — semicolon-joining is handled automatically by SDK
   sanction_list = ["Name1,ID1,Addr1", "Name2,ID2,Addr2"]
   

Empty Sanction List

Problem: PSI protocol fails with empty sanction list

Solution:

# Check list is non-empty before calling receive()
if not sanction_list:
    raise ValueError("Sanction list cannot be empty")

Session Not Found

Problem: KeyError: Unknown session: <session_id>

Cause: Wrong session ID passed to process(), or session already completed.

Solution:

from ap3operations import PSIOperation

psi = PSIOperation()          # initiator-side instance
receiver_psi = PSIOperation() # receiver-side instance (owns its own sessions)

sanction_list = ["Alice Smith,ID001,1 Main St", "Bob Jones,ID002,2 Oak Ave"]

# start() returns a dict — extract session_id from it
init_result = psi.start(role="initiator", inputs={"customer_data": "John Doe,ID123,123 Main St"})
session_id = init_result["session_id"]  # use this exact value

recv_result = receiver_psi.receive(
    role="receiver",
    message=init_result["outgoing"],
    config={"sanction_list": sanction_list},
)
final = psi.process(session_id, recv_result["outgoing"])
is_match = final["result"]["is_match"]

Agent Communication Issues

Message Not Received

Problem: Agent doesn't respond to messages

Solution:

1. Check agent logs:

   # PSI demo (Docker)
   make logs
   
   # PSI demo (local)
   # Check terminal output for each agent process
   

2. Verify message format:

   # Correct A2A message format
   from a2a.types import Message, Part, Role, SendMessageRequest
   
   msg = Message(role=Role.ROLE_USER, message_id=message_id)
   msg.context_id = context_id
   msg.parts.append(Part(text=json.dumps(protocol_data)))
   message_request = SendMessageRequest(message=msg)
   

3. Check agent card:

   async with httpx.AsyncClient() as client:
       resolver = A2ACardResolver(client, agent_url)
       card = await resolver.get_agent_card()
       print(f"Agent: {card.name}, URL: {card.url}")
   

Performance Issues

Slow Protocol Execution

Problem: PSI takes too long

Common Causes:

1. Network latency — Use local agents for testing
2. Large dataset — PSI scales with sanction list size
3. Debug logging — Disable verbose logging in production

Solution:

import logging

# Production: Only warnings and errors
logging.basicConfig(level=logging.WARNING)

# Development: Info level
logging.basicConfig(level=logging.INFO)

High Memory Usage

Problem: Python process uses excessive memory

Solution:

# Reuse PSIOperation instance across requests — sessions are cleaned up
# automatically when done=True
psi = PSIOperation()
# ... use psi for multiple requests ...

Gemini API Issues

Rate Limit Exceeded

Problem: 429 Too Many Requests

Solution:

import time
from google.api_core import retry

@retry.Retry(predicate=retry.if_exception_type(Exception))
def call_with_retry():
    # Your Gemini API call
    pass

# Or manual backoff
for attempt in range(3):
    try:
        response = agent.process(message)
        break
    except Exception as e:
        if '429' in str(e):
            time.sleep(2 ** attempt)
        else:
            raise

Quota Exhausted

Problem: Resource exhausted: Quota exceeded

Solution:

1. Check your quota: Google AI Studio
2. Use a different API key
3. Implement request batching
4. Switch to a lower-cost model

Common Error Messages

ImportError: cannot import name 'X' from 'ap3'

Cause: Incorrect import path

Solution:

# Correct imports
from ap3operations import PSIOperation        # ✓
from ap3.services import CommitmentMetadataSystem        # ✓
from ap3.types.directive import PrivacyIntentDirective   # ✓

# Wrong — these no longer exist
from ap3.operations.psi import SanctionCheck  # ✗ class removed
from ap3.operations.sfe import DotProduct     # ✗ SFE removed

pydantic.ValidationError: X field required

Cause: Missing required field in Pydantic model

Solution:

from ap3.types.directive import PrivacyIntentDirective

intent = PrivacyIntentDirective(
    ap3_session_id="session_123",         # required
    intent_directive_id="intent_001",     # required
    operation_type="PSI",                 # required — "PSI" or "PIR" only
    participants=["agent1", "agent2"],    # required — min 2 entries
    expiry="2026-12-31T23:59:59Z",        # required
    signature=None,                       # optional
)

create_commitment() missing required argument: 'data_hash'

Cause: data_hash is required but often omitted from examples.

Solution:

from ap3.services import CommitmentMetadataSystem
from ap3.types.core import DataSchema, DataStructure, DataFormat

system = CommitmentMetadataSystem()
commitment = system.create_commitment(
    agent_id="agent_01",
    data_schema=DataSchema(
        structure=DataStructure.BLACKLIST,
        format=DataFormat.STRUCTURED,
        fields=["name", "id", "address"],
    ),
    entry_count=5000,
    data_hash="sha256:abc123...",  # required
)

Debug Mode

Enable detailed debugging:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Reduce noise from http library
logging.getLogger('httpx').setLevel(logging.WARNING)

Getting Help

If you can't resolve your issue:

1. Check Examples: Review working examples in examples/psi/
2. Search Issues: GitHub Issues
3. Contact Support: [email protected]
4. Report Bug: Include:
5. AP3 version
6. Python version
7. Platform (macOS/Linux)
8. Full error traceback
9. Minimal reproduction code

Diagnostic Commands

Run these to gather information for support:

# System info
python --version
uv pip list | grep ap3
uname -a  # Linux/macOS

# Test imports
python -c "import ap3; print(ap3.__version__)"
python -c "from ap3operations import PSIOperation; print('PSIOperation OK')"
python -c "from ap3.types.directive import PrivacyIntentDirective; print('Directives OK')"

# Check binaries
ls ap3operations/psi/binaries/