Skip to main content

Troubleshooting Guide

Solutions to common issues with Oneliac.

API Connection Issues​

Issue: Cannot connect to API​

Error:

Connection refused: 127.0.0.1:8000

Diagnosis:

  1. Check if API server is running
  2. Verify correct hostname/port
  3. Check firewall rules

Solution:

# Check if server is running
ps aux | grep uvicorn

# Start server
uvicorn agents.api:app --host 0.0.0.0 --port 8000

# Test connection
curl http://localhost:8000/health

Issue: HTTPS Certificate Error​

Error:

SSL: CERTIFICATE_VERIFY_FAILED

Causes:

  • Self-signed certificate in development
  • Expired certificate in production

Solution (Development):

import urllib3
urllib3.disable_warnings()

# Or use requests with verify=False (not recommended for production)
requests.post(url, json=data, verify=False)

Solution (Production):

  1. Use valid SSL certificate
  2. Renew certificate before expiration
  3. Use Let's Encrypt for free certificates

Issue: Timeout Errors​

Error:

Request timeout after 30 seconds

Causes:

  • Slow network connection
  • Server overload
  • Proof generation taking too long

Solution:

# Increase timeout
response = requests.post(
    url,
    json=payload,
    timeout=60  # 60 seconds
)

# Or implement retry with exponential backoff
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential())
def api_call():
    return requests.post(url, json=payload, timeout=30)

Authentication Issues​

Issue: 401 Unauthorized​

Error:

{
    "detail": "Unauthorized: Invalid API key"
}

Causes:

  • Missing API key
  • Invalid API key
  • Expired API key

Solution:

# Check header includes API key
curl -H "Authorization: Bearer YOUR_API_KEY" http://api.oneliac.io/...

# Verify key format (should start with sk_)
# Regenerate key if needed
# Check key hasn't expired

Issue: 403 Forbidden​

Error:

{
    "detail": "Forbidden: Insufficient permissions"
}

Causes:

  • API key lacks required permissions
  • IP not whitelisted
  • Account restricted

Solution:

  1. Check API key permissions
  2. Verify IP whitelisting if enabled
  3. Contact support if account is restricted

Data Validation Issues​

Issue: Invalid Request Format​

Error:

{
    "detail": "Validation error: field 'patient_id' is required"
}

Cause: Missing required field or wrong type

Solution:

  1. Check request against API specification
  2. Verify all required fields present
  3. Ensure correct data types

Example:

# Correct request format
payload = {
    "patient_data": {
        "patient_id": "PAT_001",  # String
        "encrypted_data": "base64_string",  # String (Base64)
        "ipfs_cid": "QmValid...",  # String (IPFS CID)
        "data_hash": "abc123..."  # String (64 hex chars)
    },
    "procedure_code": "PROC001"  # String
}

Issue: Data Hash Mismatch​

Error:

{
    "detail": "Eligibility check failed: Data hash mismatch"
}

Cause: data_hash doesn't match encrypted data

Solution:

import hashlib
import json

# Compute correct hash
patient_data = {...}
patient_json = json.dumps(patient_data)
correct_hash = hashlib.sha256(patient_json.encode()).hexdigest()

print(f"Correct hash: {correct_hash}")
print(f"Length: {len(correct_hash)}")  # Should be 64

# Use in API call
payload["patient_data"]["data_hash"] = correct_hash

Issue: Invalid Base64 Encoding​

Error:

{
    "detail": "Invalid encrypted data format"
}

Cause: encrypted_data is not valid Base64

Solution:

import base64
from cryptography.fernet import Fernet

# Encrypt data correctly
encryption_key = Fernet.generate_key()
cipher = Fernet(encryption_key)

plaintext = json.dumps(patient_data).encode()
encrypted_bytes = cipher.encrypt(plaintext)
encrypted_b64 = base64.b64encode(encrypted_bytes).decode('utf-8')

# Verify Base64
try:
    base64.b64decode(encrypted_b64)
    print("Valid Base64")
except Exception as e:
    print(f"Invalid Base64: {e}")

Issue: Invalid IPFS CID​

Error:

{
    "detail": "Invalid IPFS CID format"
}

Cause: ipfs_cid format incorrect

Solution:

# Valid IPFS CID formats
valid_cids = [
    "QmV5koooi6jKRBXDo",  # v0 format (Qm...)
    "bafyreigdyry..."    # v1 format (bafy...)
]

# Validate CID
def validate_ipfs_cid(cid):
    if cid.startswith("Qm") and len(cid) > 40:
        return True
    if cid.startswith("bafy") and len(cid) > 50:
        return True
    return False

# Or use IPFS library
from ipfshttpclient import cid
try:
    cid.from_string(your_cid)
    print("Valid CID")
except Exception as e:
    print(f"Invalid CID: {e}")

Encryption Issues​

Issue: Decryption Failed​

Error:

{
    "detail": "Decryption failed: Invalid token"
}

Cause: Encrypted data doesn't match encryption key

Solution:

from cryptography.fernet import Fernet, InvalidToken

encryption_key = Fernet.generate_key()
cipher = Fernet(encryption_key)

# Encrypt
plaintext = b"test data"
encrypted = cipher.encrypt(plaintext)

# Decrypt with correct key
try:
    decrypted = cipher.decrypt(encrypted)
    print("Decryption successful")
except InvalidToken:
    print("Invalid encryption key or data")

# WRONG: Using different key
wrong_key = Fernet.generate_key()
wrong_cipher = Fernet(wrong_key)
# This will fail:
# wrong_cipher.decrypt(encrypted)  # InvalidToken

Issue: Lost Encryption Key​

Problem: Encrypted data cannot be decrypted (key lost)

Prevention:

  1. Store encryption keys in secure key management system
  2. Back up keys to separate secure location
  3. Never commit keys to version control
  4. Use environment variables or secrets manager

Recovery:

  • If key is lost, encrypted data cannot be recovered
  • Implement key rotation strategy before this happens

Eligibility Check Issues​

Issue: Unexpected "Not Eligible" Result​

Problem: Patient should be eligible but returns false

Diagnosis:

  1. Check patient data is correct
  2. Verify procedure code exists
  3. Validate data hasn't been corrupted

Solution:

# Verify patient data
print(f"Patient ID: {patient_data['patient_id']}")
print(f"Procedure: {procedure_code}")

# Verify procedure code exists
valid_procedures = ['PROC001', 'PROC002', 'PROC003']
if procedure_code not in valid_procedures:
    print(f"Invalid procedure: {procedure_code}")

# Try with different procedure
response = verify_eligibility(patient_data, 'PROC001')
print(f"Response: {response}")

Issue: Slow Eligibility Checks​

Problem: Eligibility checks taking >1 second

Causes:

  1. Network latency
  2. Server overload
  3. Proof generation timeout
  4. Blockchain congestion

Solution:

# Monitor response times
import time

start = time.time()
response = verify_eligibility(patient_data, procedure)
duration = time.time() - start

print(f"Response time: {duration:.3f}s")

if duration > 1.0:
    print("Slow response. Possible causes:")
    print("- Server load high")
    print("- Network latency high")
    print("- Blockchain congested")
    
    # Retry later
    time.sleep(30)
    retry_response = verify_eligibility(patient_data, procedure)

Prescription Validation Issues​

Issue: Drug Interaction Detected Unexpectedly​

Problem: Drug interaction found but patient not on conflicting drug

Cause: Patient data mismatch or incorrect interaction database

Solution:

# Check patient's current medications
patient_medical_history = {
    "medications": [
        "metoprolol",
        "lisinopril"
    ],
    "allergies": ["penicillin"]
}

# Check drug interaction rules
drug_interactions = {
    "DRUG001": {
        "interactions": ["DRUG002"],  # Warfarin + NSAID = bad
        "contraindications": ["penicillin"]
    }
}

# If drug is on contraindication list, will be rejected

Issue: "Drug Not Found" Error​

Error:

{
    "detail": "Drug code DRUG999 not found"
}

Solution:

  1. Verify drug code against reference database
  2. Contact support to add new drug code
  3. Check current list of supported drugs

Federated Learning Issues​

Issue: Round Submission Timeout​

Error:

{
    "detail": "Federated learning submission failed: Timeout"
}

Causes:

  • Patient batch too large
  • Network latency
  • Server overload

Solution:

# Reduce batch size
patient_batch = patient_list[:1000]  # Max 1000 per submission

# Or split into multiple submissions
for i in range(0, len(patient_list), 1000):
    batch = patient_list[i:i+1000]
    submit_federated_update(batch, round_num)

# Retry with exponential backoff
from tenacity import retry, wait_exponential

@retry(wait=wait_exponential(multiplier=1, min=4, max=60))
def submit_with_retry(batch):
    return submit_federated_update(batch, round_num)

Issue: Model Hash Mismatch​

Problem: Different hospitals report different model hashes for same round

Cause: Gradient computation or aggregation inconsistency

Solution:

  1. Ensure all hospitals submit in same round
  2. Check encryption key consistency
  3. Verify data preprocessing is identical
  4. Contact support if persists

Server Issues​

Issue: 500 Internal Server Error​

Error:

{
    "detail": "Internal server error"
}

Diagnosis:

  1. Check server logs
  2. Verify database connection
  3. Test blockchain connection
  4. Check system resources

Solution:

# Check server logs
tail -f /var/log/oneliac.log

# Check system resources
top  # CPU and memory
df -h  # Disk space
netstat -an  # Network connections

# Restart server
pkill -f uvicorn
uvicorn agents.api:app --host 0.0.0.0 --port 8000

Issue: 503 Service Unavailable​

Error:

{
    "detail": "Service unavailable"
}

Causes:

  • Server down for maintenance
  • Database unavailable
  • Blockchain node offline

Solution:

# Check health status
curl http://api.oneliac.io/health

# Check status page
curl http://api.oneliac.io/status

# If offline, wait for maintenance to complete
# Check status page or contact support

Performance Issues​

Issue: High Latency​

Problem: API responses taking >5 seconds

Solution:

# Profile response times by component
metrics = {
    "encrypt": 50,  # ms
    "api_call": 400,  # ms
    "proof_generation": 200,  # ms
    "blockchain": 300,  # ms
    "total": 950  # ms
}

# Optimize slowest component
# - Network: Use connection pooling
# - Proof: Pre-compute if possible
# - Server: Check load, scale up

Issue: High Error Rate​

Problem: >5% of requests failing

Solution:

# Track error rate
total = 1000
errors = 60
error_rate = (errors / total) * 100  # 6%

# Analyze by type
by_type = {
    "validation": 30,  # Bad input
    "timeout": 15,     # Server/network
    "auth": 10,        # Key issues
    "other": 5
}

# Fix validation errors first (client-side)
# Then address server/network issues

Getting Help​

If you can't resolve the issue:

  1. Check Documentation: This guide
  2. Search Issues: https://github.com/orgs/Oneliac/issues
  3. Telegram: https://t.me/oneliac_bot
  4. GitHub Organization: https://github.com/orgs/Oneliac

Reporting Bugs​

Include:

  • Error message (full stack trace)
  • Reproduction steps
  • Expected vs actual behavior
  • System info (OS, Python version, Oneliac version)
  • Code sample if possible