Troubleshooting

Quick Diagnostics

Check service status

docker compose ps

All services should show Up or Up (healthy) status.

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f pentagi

Test connectivity

# PentAGI API
curl -k https://localhost:8443/health

# Database
docker compose exec pgvector psql -U postgres -c "SELECT 1"

# Worker node (if configured)
curl -k --cert /opt/pentagi/docker-host-ssl/cert.pem \
  --key /opt/pentagi/docker-host-ssl/key.pem \
  --cacert /opt/pentagi/docker-host-ssl/ca.pem \
  https://${PRIVATE_IP}:2376/version

Common Issues

Network and Connectivity

Error: Network pentagi-network not found

Problem: Optional stacks started before main stackSolution:

# Start main stack first to create networks
docker compose -f docker-compose.yml up -d

# Then start optional stacks
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d

Prevention: Always start docker-compose.yml first, then add optional stacks.

Cannot connect to PentAGI at localhost:8443

Possible causes:

Service not started
Port binding issue
Firewall blocking access

Diagnosis:

# Check if pentagi is running
docker compose ps pentagi

# Check port binding
docker compose port pentagi 8443

# Check logs for errors
docker compose logs pentagi | grep -i error

# Test local connectivity
curl -k https://localhost:8443/health

Solutions:

# Restart service
docker compose restart pentagi

# Change listen IP if needed (edit .env)
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443

# Check firewall
sudo ufw status
sudo ufw allow 8443/tcp

SSL certificate errors

Problem: Self-signed certificate warnings or connection refusedFor development (self-signed certificates):

# Access with -k flag to skip verification
curl -k https://localhost:8443/health

# Or add certificate to browser trust store
docker compose cp pentagi:/opt/pentagi/ssl/cert.pem ./pentagi-cert.pem
# Import pentagi-cert.pem to browser

For production (Let’s Encrypt):

# Verify certificate paths in .env
SERVER_SSL_CRT=/etc/letsencrypt/live/pentagi.example.com/fullchain.pem
SERVER_SSL_KEY=/etc/letsencrypt/live/pentagi.example.com/privkey.pem

# Check certificate is mounted
docker compose exec pentagi ls -la /etc/ssl/pentagi/

# Test certificate validity
openssl s_client -connect localhost:8443 -servername pentagi.example.com

Worker node TLS connection failures

Problem: PentAGI cannot connect to worker node Docker APIDiagnosis:

# On main node - test connection
docker --tlsverify \
  --tlscacert=/opt/pentagi/docker-host-ssl/ca.pem \
  --tlscert=/opt/pentagi/docker-host-ssl/cert.pem \
  --tlskey=/opt/pentagi/docker-host-ssl/key.pem \
  -H tcp://${PRIVATE_IP}:2376 version

# Check certificate validity
openssl x509 -in /opt/pentagi/docker-host-ssl/cert.pem -noout -dates

# Verify SAN includes worker IP
openssl x509 -in /opt/pentagi/docker-host-ssl/cert.pem -noout -text | grep -A1 "Subject Alternative Name"

Solutions:

# Regenerate certificates if SAN is missing
# See worker node guide for certificate generation

# Check firewall on worker node
sudo ufw status | grep 2376

# Verify Docker daemon is listening
sudo netstat -tlnp | grep 2376

# Check Docker daemon logs
sudo journalctl -u docker -n 100

Database Issues

PostgreSQL connection refused

Diagnosis:

# Check if PostgreSQL is running
docker compose ps pgvector

# Check logs
docker compose logs pgvector

# Test connection
docker compose exec pgvector psql -U postgres -c "SELECT version()"

Solutions:

# Restart PostgreSQL
docker compose restart pgvector

# Check credentials in .env
PENTAGI_POSTGRES_USER=postgres
PENTAGI_POSTGRES_PASSWORD=correct_password

# Verify connection string
docker compose exec pentagi env | grep DATABASE_URL

Database migration errors

Problem: Schema version mismatch or migration failuresDiagnosis:

# Check migration status
docker compose logs pentagi | grep -i migration

# Check database tables
docker compose exec pgvector psql -U postgres -d pentagidb -c "\dt"

Solutions:

# For clean install - recreate database
docker compose down
docker volume rm pentagi-postgres-data
docker compose up -d

# For production - manual migration
docker compose exec pgvector psql -U postgres -d pentagidb
# Run migration SQL manually

Neo4j connection issues (Graphiti)

Diagnosis:

# Check Neo4j status
docker compose -f docker-compose-graphiti.yml ps neo4j

# Check logs
docker compose -f docker-compose-graphiti.yml logs neo4j

# Test Bolt connection
docker compose -f docker-compose-graphiti.yml exec neo4j \
  cypher-shell -u neo4j -p ${NEO4J_PASSWORD} "RETURN 1"

Solutions:

# Restart Neo4j
docker compose -f docker-compose-graphiti.yml restart neo4j

# Check credentials
docker compose -f docker-compose-graphiti.yml exec graphiti env | grep NEO4J

# Increase memory if needed (edit docker-compose-graphiti.yml)
services:
  neo4j:
    shm_size: 8g
    environment:
      NEO4J_dbms_memory_heap_initial__size: 2G
      NEO4J_dbms_memory_heap_max__size: 4G

Service-Specific Issues

Langfuse: Failed to initialize project

Problem: Langfuse initialization errors or missing projectSolutions:

# Check initialization environment variables
docker compose -f docker-compose-langfuse.yml exec langfuse-web env | grep LANGFUSE_INIT

# Restart Langfuse services
docker compose -f docker-compose-langfuse.yml restart

# Check database migrations
docker compose -f docker-compose-langfuse.yml logs langfuse-web | grep migration

# Recreate Langfuse database if needed
docker compose -f docker-compose-langfuse.yml down
docker volume rm langfuse-postgres-data
docker compose -f docker-compose-langfuse.yml up -d

Scraper: Connection timeout or 502 errors

Problem: Web scraper not responding or timing outDiagnosis:

# Check scraper status
docker compose ps scraper

# Check logs
docker compose logs scraper | tail -50

# Test scraper directly
curl -k -u someuser:somepass https://localhost:9443/health

Solutions:

# Increase memory for scraper (edit docker-compose.yml)
services:
  scraper:
    shm_size: 4g

# Reduce concurrent sessions
LOCAL_SCRAPER_MAX_CONCURRENT_SESSIONS=5

# Restart scraper
docker compose restart scraper

Graphiti: Entity extraction failures

Problem: Knowledge graph not building or entity extraction errorsDiagnosis:

# Check Graphiti logs
docker compose -f docker-compose-graphiti.yml logs graphiti

# Test Graphiti API
curl http://localhost:8000/healthcheck

# Check OpenAI key
docker compose -f docker-compose-graphiti.yml exec graphiti env | grep OPENAI

Solutions:

# Verify OpenAI API key is valid
OPEN_AI_KEY=sk-...

# Check model name is correct
GRAPHITI_MODEL_NAME=gpt-4o-mini

# Increase timeout
GRAPHITI_TIMEOUT=60

# Restart Graphiti
docker compose -f docker-compose-graphiti.yml restart graphiti

LLM Provider Issues

No LLM provider configured

Error: Error: No LLM provider configured. Please set at least one provider.Solution:

# Edit .env and add at least one provider
OPEN_AI_KEY=sk-...
# OR
ANTHROPIC_API_KEY=sk-ant-...
# OR
GEMINI_API_KEY=...

# Restart PentAGI
docker compose restart pentagi

OpenAI API rate limit exceeded

Problem: Hitting rate limits or quota errorsSolutions:

# Use different models with higher limits
# Edit agent configuration to use cheaper models

# Add delays between requests (future feature)

# Use multiple API keys with load balancing (future feature)

# Switch to Anthropic or other provider temporarily
ANTHROPIC_API_KEY=sk-ant-...

AWS Bedrock rate limits

Problem: Very low default rate limits (2 RPM for Claude Sonnet 4)Solutions:

# Request quota increase via AWS Service Quotas console
# Path: Service Quotas > AWS Bedrock > Model rate limits

# Switch to provisioned throughput
BEDROCK_USE_PROVISIONED_THROUGHPUT=true

# Use alternative models with higher quotas
# Edit Bedrock provider config to use Nova or Llama models

# Switch to different LLM provider
ANTHROPIC_API_KEY=sk-ant-...  # Direct API has higher limits

Ollama connection refused

Problem: Cannot connect to Ollama serverDiagnosis:

# Test Ollama API
curl http://localhost:11434/api/tags

# Check if Ollama is running
ps aux | grep ollama

# Check Ollama logs
journalctl -u ollama -n 100

Solutions:

# Start Ollama if not running
systemctl start ollama

# Verify server URL in .env
OLLAMA_SERVER_URL=http://localhost:11434

# For Docker Ollama
OLLAMA_SERVER_URL=http://host.docker.internal:11434

# Pull required model
ollama pull llama3.1:8b-instruct-q8_0

Resource Issues

Out of memory errors

Symptoms: Services crashing, OOM kill messages in logsDiagnosis:

# Check Docker memory usage
docker stats

# Check system memory
free -h

# Check OOM kills
dmesg | grep -i kill
docker compose logs | grep -i "out of memory"

Solutions:

# Increase system swap
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Reduce concurrent workers
# Via PentAGI UI or configuration

# Increase memory limits in docker-compose.yml
services:
  pentagi:
    deploy:
      resources:
        limits:
          memory: 8G

# Stop unused stacks
docker compose -f docker-compose-langfuse.yml down

Disk space exhausted

Diagnosis:

# Check disk usage
df -h

# Check Docker disk usage
docker system df -v

# Check volume sizes
docker volume ls --format '{{.Name}}' | \
  xargs -I {} sh -c 'echo "Volume: {}"; docker volume inspect {} --format "{{.Mountpoint}}" | xargs du -sh'

Solutions:

# Clean up Docker system
docker system prune -a --volumes

# Remove old images
docker image prune -a --filter "until=168h"

# Clean up logs
docker compose logs --no-log-prefix > /dev/null

# Reduce log retention (edit docker-compose.yml)
logging:
  options:
    max-size: 10m
    max-file: "3"

High CPU usage

Diagnosis:

# Check CPU usage by container
docker stats --no-stream

# Check top processes
docker compose top

# Check system load
uptime
top

Solutions:

# Limit CPU for containers (edit docker-compose.yml)
services:
  pentagi:
    deploy:
      resources:
        limits:
          cpus: '2'

# Reduce concurrent operations
# Via PentAGI configuration

# Check for runaway processes
docker compose exec pentagi ps aux | sort -nrk 3,3 | head -5

Container Issues

Container keeps restarting

Diagnosis:

# Check restart count
docker compose ps

# Check exit code
docker compose ps -a | grep pentagi

# View logs for errors
docker compose logs --tail=100 pentagi

# Check events
docker events --filter 'container=pentagi' --since 10m

Common exit codes:

Exit 0: Normal exit (shouldn’t restart unless misonfigured)
Exit 1: Application error (check logs)
Exit 137: OOM killed (increase memory)
Exit 139: Segmentation fault (bug or corruption)

Solutions:

# Stop auto-restart temporarily to debug
docker update --restart=no pentagi

# Fix underlying issue (check logs)
# Then re-enable restart
docker update --restart=unless-stopped pentagi

Cannot execute binary inside container

Problem: Permission denied or exec format errorSolutions:

# Check architecture
docker compose exec pentagi uname -m

# For ARM64 systems using AMD64 images
docker pull --platform linux/amd64 vxcontrol/pentagi:latest

# For permission issues
docker compose exec pentagi chmod +x /path/to/binary

Performance Issues

Slow response times

Diagnosis:

# Check system resources
docker stats

# Check database performance
docker compose exec pgvector psql -U postgres -d pentagidb -c \
  "SELECT pid, now() - query_start as duration, query 
   FROM pg_stat_activity 
   WHERE state = 'active' ORDER BY duration DESC"

# Check network latency
docker compose exec pentagi ping -c 5 pgvector

Solutions:

Follow Performance Optimization guide
Add database indexes
Increase resource limits
Use faster storage (NVMe SSD)

LLM requests timing out

Problem: LLM API calls failing with timeout errorsDiagnosis:

# Check logs for timeout errors
docker compose logs pentagi | grep -i timeout

# Test LLM provider connectivity
docker compose exec pentagi curl -v https://api.openai.com/v1/models

# Check proxy settings
docker compose exec pentagi env | grep -i proxy

Solutions:

# Increase timeout values (future configuration option)

# Check network connectivity
docker compose exec pentagi ping -c 3 api.openai.com

# Use different provider endpoint
OPEN_AI_SERVER_URL=https://api.openai.com/v1

# Configure proxy if needed
PROXY_URL=http://proxy.example.com:8080

Installer Issues

Installer fails to start or crashes

Problem: Terminal breaks or installer doesn’t display correctlySolutions:

# Ensure terminal supports TUI
echo $TERM  # Should be xterm-256color or similar

# Run in proper terminal emulator
# Not in: screen, tmux, or IDE integrated terminals

# Check minimum terminal size
tput cols  # Should be >= 80
tput lines # Should be >= 24

# Check logs
tail -f log.json | jq '.'

Cannot save configuration

Problem: Environment variables not persistingDiagnosis:

# Check .env file permissions
ls -la .env

# Verify .env file is being written
cat .env | grep OPEN_AI_KEY

Solutions:

# Ensure .env is writable
chmod 644 .env

# Remove inline comments (can break parsing)
perl -i -pe 's/\s+#.*$//' .env

# Verify no duplicate entries
sort .env | uniq -c | grep -v "^\s*1"

Emergency Procedures

Complete system reset

This will delete all data! Only use as last resort.

# Stop all services
docker compose -f docker-compose.yml \
  -f docker-compose-langfuse.yml \
  -f docker-compose-graphiti.yml \
  -f docker-compose-observability.yml \
  down -v

# Remove all volumes
docker volume ls | grep pentagi | awk '{print $2}' | xargs docker volume rm
docker volume ls | grep langfuse | awk '{print $2}' | xargs docker volume rm
docker volume ls | grep neo4j | awk '{print $2}' | xargs docker volume rm

# Remove networks
docker network rm pentagi-network langfuse-network observability-network

# Clean Docker system
docker system prune -a --volumes

# Restart from scratch
docker compose up -d

Restore from backup

# Stop services
docker compose down

# Restore .env
cp /opt/pentagi/backups/.env.backup .env

# Restore PostgreSQL
docker compose up -d pgvector
sleep 10
gunzip -c /opt/pentagi/backups/pentagi_latest.sql.gz | \
  docker compose exec -T pgvector psql -U postgres -d pentagidb

# Restore Neo4j (if using Graphiti)
docker compose -f docker-compose-graphiti.yml up -d neo4j
sleep 10
docker compose -f docker-compose-graphiti.yml exec neo4j \
  neo4j-admin database load neo4j --from-path=/backups/neo4j_latest.dump

# Start all services
docker compose -f docker-compose.yml \
  -f docker-compose-langfuse.yml \
  -f docker-compose-graphiti.yml \
  -f docker-compose-observability.yml \
  up -d

Getting Help

Community Support

Join the Discord community for help

Telegram Group

Connect with users on Telegram

GitHub Issues

Report bugs or request features

Documentation

Browse the complete documentation

Providing Debug Information

When requesting help, include:

# System information
uname -a
docker version
docker compose version

# Service status
docker compose ps

# Recent logs
docker compose logs --tail=100 pentagi > pentagi.log

# Resource usage
docker stats --no-stream

# Environment (sanitized)
grep -v "KEY\|PASSWORD\|SECRET" .env

Next Steps

Docker Compose Deployment

Standard deployment guide

Production Best Practices

Optimize for production

Worker Node Setup

Distributed architecture

Configuration Reference

Complete configuration guide

Get Started

Core Concepts

Configuration

Deployment

Features

Development

Troubleshooting

Quick Diagnostics

Common Issues

Network and Connectivity

Database Issues

Service-Specific Issues

LLM Provider Issues

Resource Issues

Container Issues

Performance Issues

Installer Issues

Emergency Procedures

Getting Help

Community Support

Telegram Group

GitHub Issues

Documentation

Providing Debug Information

Next Steps

Docker Compose Deployment

Production Best Practices

Worker Node Setup

Configuration Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Deployment

Features

Development

Documentation Index

​Quick Diagnostics

​Common Issues

​Network and Connectivity

​Database Issues

​Service-Specific Issues

​LLM Provider Issues

​Resource Issues

​Container Issues

​Performance Issues

​Installer Issues

​Emergency Procedures

​Getting Help

Community Support

Telegram Group

GitHub Issues

Documentation

​Providing Debug Information

​Next Steps

Docker Compose Deployment

Production Best Practices

Worker Node Setup

Configuration Reference

Build docs developers (and LLMs) love

Quick Diagnostics

Common Issues

Network and Connectivity

Database Issues

Service-Specific Issues

LLM Provider Issues

Resource Issues

Container Issues

Performance Issues

Installer Issues

Emergency Procedures

Getting Help

Providing Debug Information

Next Steps