Troubleshooting

Common issues and how to fix them.

Connection Issues

”Connection refused” to TypeDB

Symptoms:

ConnectionError: Unable to connect to TypeDB Cloud

Solutions:

1. Check VPN - Disable VPN (TypeDB Cloud uses direct connection)

2. Verify credentials:

cat .env
# Should have:
# TYPEDB_ADDRESS=https://cr0mc4-0.cluster.typedb.com:80
# TYPEDB_DATABASE=ants-colony
# TYPEDB_USERNAME=your-username
# TYPEDB_PASSWORD=your-password
# TYPEDB_TLS=true

3. Test connection:

from ants.knowledge import TypeDBClient

client = TypeDBClient()
try:
    await client.connect()
    print("Connected!")
except Exception as e:
    print(f"Failed: {e}")

“401 Unauthorized” from Gateway

Symptoms:

{"error": "unauthorized", "message": "Invalid or expired token"}

Solutions:

1. Re-register:

ants-worker leave
ants-worker join

2. Check token manually:

cat ~/.ants/config.json

3. Verify token works:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://api.ants-at-work.com/stats

“429 Too Many Requests”

Symptoms:

{"error": "rate_limited", "retry_after": 60}

Solutions:

Wait and retry. Rate limits:

• /register: 10/hour per IP
• /dp: 100/minute per worker
• Others: 120/minute per worker

Import Errors

”ModuleNotFoundError: No module named ‘ants’”

Solutions:

1. Activate virtual environment:

source venv/bin/activate  # Unix
venv\Scripts\activate     # Windows

2. Install in editable mode:

pip install -e .

3. Verify installation:

python -c "from ants import Scout; print('OK')"

“ImportError: cannot import name ‘X’”

Solutions:

1. Update to latest:

git pull origin main
pip install -e .

2. Check Python version:

python --version
# Should be 3.10+

Worker Issues

Worker not finding points

Symptoms:

• Running for hours with no distinguished points

Solutions:

1. Check if actually running:

ants-worker status

2. Verify hardware detection:

ants-worker info --detailed

3. Try different backend:

ants-worker join -b parallel_cpu --workers 8

4. Check logs:

ANTS_LOG_LEVEL=DEBUG ants-worker join

CUDA not detected

Symptoms:

GPU: None detected

Solutions:

1. Check NVIDIA driver:

nvidia-smi

2. Check CUDA:

nvcc --version

3. Reinstall with CUDA:

pip uninstall ants-worker
pip install ants-worker[cuda]

Performance lower than expected

Check for:

1. Thermal throttling:

nvidia-smi -l 1
# Watch temperature and clock speeds

2. Other GPU processes:

nvidia-smi
# Check memory usage

3. Power mode:

# Try turbo mode
ants-worker join --turbo

Query Errors

”Variable not bound”

Symptoms:

TypeQLError: Variable $x is not bound

Solution: Make sure all variables are defined in match:

# Wrong
match $e isa edge; select $x;

# Correct
match $e isa edge, has id $x; select $x;

“Type not found”

Symptoms:

TypeQLError: Type 'my_type' not found

Solution: Check schema is loaded:

# In TypeDB console
transaction ants-colony data-read
match $t type my_type; fetch $t;

Query returns empty

Solutions:

1. Check data exists:

match $a isa ant; reduce $count = count;

2. Simplify query:

# Start simple
match $a isa ant; limit 5;

# Add constraints one at a time
match $a isa ant, has caste "scout"; limit 5;

TypeQL 3.0 Gotchas

Aggregations syntax changed

# OLD (2.x) - doesn't work
match $a isa ant; count;

# NEW (3.0) - correct
match $a isa ant; reduce $count = count;

Getting values from results

# Wrong
value = row.get("x")

# Correct
value = row.get("x").as_attribute().get_value()
# Or for aggregates:
value = row.get("count").get_integer()

Getting Help

If none of these solutions work:

1. Discord #tech-support - Fastest response
2. GitHub Issues - For bugs
3. Mentor office hours - During hackathon

Include in your report:

• Error message (full traceback)
• Steps to reproduce
• OS and Python version
• Output of ants-worker info (if relevant)