Troubleshooting

​

Overview

​

Docker Issues

​

Build Fails with Git Dependency Error

ERROR: Could not find a version that satisfies the requirement discord.py-self

# Clear Docker cache
docker builder prune

# Rebuild without cache
docker build --no-cache -t junkie:latest .

RUN apt-get update && \
    apt-get install -y --no-install-recommends git && \
    rm -rf /var/lib/apt/lists/*

​

Container Exits Immediately

1. Check logs:
   docker logs junkie-bot
   
2. Run interactively:
   docker run -it --env-file .env junkie:latest /bin/bash
   # Then manually run: python main.py
   
3. Common causes:
   • Missing environment variables
   • Invalid database connection
   • Missing API keys
   • Python import errors

​

uv Installation Fails

ERROR: pip install uv failed

RUN pip install uv==0.1.0

RUN pip install -r requirements.txt

​

Environment Variable Issues

​

Variables Not Loading

1. Verify .env file location:
   ls -la .env
   # Should be in project root
   
2. Check file syntax:
   cat .env
   # Ensure no spaces around = signs
   # Correct: POSTGRES_URL=postgresql://...
   # Wrong:   POSTGRES_URL = postgresql://...
   
3. Test loading:
   from dotenv import load_dotenv
   import os
   
   load_dotenv()
   print(os.getenv("POSTGRES_URL"))
   
4. Docker: Pass via —env-file:
   docker run --env-file .env junkie:latest
   

​

Missing Required Variables

KeyError: 'POSTGRES_URL'

# Minimum required
POSTGRES_URL=postgresql://user:pass@host:port/db
GROQ_API_KEY=gsk_...
CUSTOM_PROVIDER=groq
CUSTOM_MODEL=openai/gpt-oss-120b

import os
from dotenv import load_dotenv

load_dotenv()

required = ["POSTGRES_URL", "GROQ_API_KEY"]
missing = [v for v in required if not os.getenv(v)]

if missing:
    raise ValueError(f"Missing: {missing}")

​

Database Connection Issues

​

Connection Refused

psycopg2.OperationalError: could not connect to server: Connection refused

1. Verify connection string format:
   postgresql://[user]:[password]@[host]:[port]/[database]
   
2. Test connection:
   psql "$POSTGRES_URL"
   
3. Check network access:
   # Test if host is reachable
   ping db.example.com
   
   # Test if port is open
   nc -zv db.example.com 5432
   
4. Common issues:
   • Database not running
   • Firewall blocking port 5432
   • Incorrect host/port
   • Database not accepting external connections

​

Authentication Failed

psycopg2.OperationalError: FATAL: password authentication failed

1. Verify credentials:
   # URL-encode special characters in password
   # Example: p@ssw0rd! -> p%40ssw0rd%21
   
2. Test manually:
   psql -h host -p 5432 -U user -d database
   # Enter password when prompted
   
3. Check user permissions:
   -- As database admin
   GRANT ALL PRIVILEGES ON DATABASE junkie TO junkie_user;
   

​

SSL Required

psycopg2.OperationalError: SSL connection is required

POSTGRES_URL=postgresql://user:pass@host:5432/db?sslmode=require

​

API Key Issues

​

Invalid API Key

openai.error.AuthenticationError: Invalid API key

1. Check key format:
   echo $GROQ_API_KEY
   # Should start with gsk_ for Groq
   # No extra spaces or quotes
   
2. Verify key is active:
   • Check provider dashboard
   • Ensure key hasn’t been revoked
   • Check usage limits
3. Test API call:
   curl https://api.groq.com/openai/v1/models \
     -H "Authorization: Bearer $GROQ_API_KEY"
   

​

Rate Limit Exceeded

openai.error.RateLimitError: Rate limit exceeded

1. Reduce agent retries:
   AGENT_RETRIES=1  # Lower from default 2
   
2. Reduce max concurrent agents:
   MAX_AGENTS=50  # Lower from default 100
   
3. Upgrade API plan or wait for rate limit reset

​

Provider Not Found

ValueError: Unknown provider: xyz

# Valid providers (depends on your setup)
CUSTOM_PROVIDER=groq
# Or
CUSTOM_PROVIDER=openai

​

Phoenix Tracing Issues

​

Tracing Not Working

1. Check if tracing is enabled:
   echo $TRACING  # Should be "true"
   
2. Verify API key:
   echo $PHOENIX_API_KEY  # Should not be empty
   
3. Check logs for initialization:
   docker logs junkie-bot | grep -i phoenix
   # Should see: "Phoenix tracing enabled (project: ...)"
   
4. Common issues:
   • TRACING=false or not set
   • Missing PHOENIX_API_KEY
   • arize-phoenix package missing from requirements.txt
   • Network issues

​

Phoenix Import Error

ImportError: No module named 'phoenix'

arize-phoenix
langtrace-python-sdk
openinference-instrumentation-agno
opentelemetry-sdk
opentelemetry-exporter-otlp

pip install -r requirements.txt
# Or rebuild Docker image
docker build -t junkie:latest .

​

Phoenix High Overhead

1. Ensure batching is enabled (core/observability.py:38):
   tracer_provider = register(
       batch=True,  # Must be True
   )
   
2. Sample traces:
   # Only trace 10% of requests
   import random
   if random.random() < 0.1:
       setup_phoenix_tracing()
   
3. Disable in development:
   TRACING=false  # For local dev
   

​

Railway Deployment Issues

​

Build Fails on Railway

1. Check build logs:
   • Go to “Deployments” tab
   • Click failed deployment
   • Review build output
2. Common causes:
   • Missing dependencies in requirements.txt
   • Invalid Dockerfile syntax
   • Out of memory during build

docker build -t junkie:latest .

​

Service Won’t Start

1. Check runtime logs:
   • Go to “Logs” tab
   • Look for error messages
2. Verify environment variables:
   • Go to “Variables” tab
   • Ensure all required vars are set
3. Test locally with same environment:
   # Export Railway variables
   export POSTGRES_URL="..."
   export GROQ_API_KEY="..."
   
   # Run locally
   python main.py
   

​

Database Connection Fails on Railway

1. Click on PostgreSQL service
2. Copy “Database URL”
3. Set as POSTGRES_URL in your service variables

postgresql://postgres:[password]@[internal-host]:5432/railway

​

Performance Issues

​

High Memory Usage

# Check container memory
docker stats junkie-bot

1. Reduce max agents:
   MAX_AGENTS=50  # Lower from 100
   
2. Disable debug mode:
   DEBUG_MODE=false
   
3. Reduce context limits:
   CONTEXT_AGENT_MAX_MESSAGES=25000  # Lower from 50000
   

​

Slow Response Times

1. Check Phoenix traces for bottlenecks
2. Profile database queries
3. Monitor API latencies

1. Reduce temperature (faster but less creative):
   MODEL_TEMPERATURE=0.1  # Lower from 0.3
   
2. Use faster model:
   CUSTOM_MODEL=gemini-2.5-flash-lite  # Faster than GPT-4
   
3. Optimize agent retries:
   AGENT_RETRIES=1  # Lower from 2
   

​

Debugging Tips

​

Enable Debug Mode

DEBUG_MODE=true
DEBUG_LEVEL=3  # Maximum verbosity

​

Check Application Logs

# Docker
docker logs -f junkie-bot

# Railway
# Use web dashboard Logs tab

# Local
python main.py 2>&1 | tee app.log

​

Test Components Individually

# Test database connection
import psycopg2
from core.config import POSTGRES_URL

conn = psycopg2.connect(POSTGRES_URL)
print("Database connected!")

# Test API key
import openai
from core.config import GROQ_API_KEY

client = openai.OpenAI(api_key=GROQ_API_KEY)
print("API key valid!")

# Test Phoenix
from core.observability import setup_phoenix_tracing

tracer = setup_phoenix_tracing()
print(f"Phoenix initialized: {tracer is not None}")

​

Use Interactive Container

# Start container with shell
docker run -it --env-file .env junkie:latest /bin/bash

# Inside container:
python -c "import core.config; print(core.config.POSTGRES_URL)"
python main.py

​

Getting Help

1. Check logs with DEBUG_MODE=true
2. Review configuration in core/config.py
3. Test dependencies are installed correctly
4. Verify environment variables are loaded
5. Check network connectivity to external services

​

Common Error Messages

​

ModuleNotFoundError

ModuleNotFoundError: No module named 'xyz'

pip install -r requirements.txt
# Or rebuild Docker image

​

ImportError: discord.py-self

ImportError: No module named 'discord'

​

OSError: [Errno 28] No space left on device

docker system prune -a
docker volume prune

​

Next Steps

• Environment Setup - Review configuration
• Monitoring - Set up observability
• Docker Deployment - Review Docker setup