Troubleshooting

Diagnostic Tools

Check Service Status

# View all service status
docker compose ps

# View service health status
docker inspect glean-backend --format='{{.State.Health.Status}}'

View Logs

# View all service logs
docker compose logs -f

# View specific service logs
docker compose logs -f backend
docker compose logs -f worker

# View last 100 lines
docker compose logs --tail=100 backend

Resource Usage

# View resource usage
docker stats

Common Issues

Services Won’t Start

Port Conflicts

Symptom: Service fails to start, logs show port already in use.

Solution:

# Check port usage
lsof -i :80
lsof -i :3001

# Change ports
echo "WEB_PORT=8080" >> .env
echo "ADMIN_PORT=8081" >> .env

Database Connection Failed

Symptom: Backend service fails to start, logs show database connection error.

Solution:

# Check PostgreSQL status
docker compose ps postgres

# Wait for database to be ready
docker exec glean-postgres pg_isready -U glean

# Check database logs
docker compose logs postgres

Backend Service Unhealthy

Check Health Endpoint

curl http://localhost/api/health

Check Log Errors

docker compose logs backend | grep -i error

Restart Service

docker compose restart backend

Worker Not Working

Check Worker Status

docker compose ps worker
docker compose logs worker

Check Redis Connection

docker exec glean-redis redis-cli ping
# Should return PONG

Restart Worker

docker compose restart worker

RSS Feeds Not Updating

Check Worker Logs

docker compose logs worker | grep -i feed

Manually Trigger Refresh

Click the refresh button on the feed in the Web interface.

Check Feed Status

View feed error status in the Web interface.

Cannot Access Web Interface

Check Web Service

docker compose ps web
docker compose logs web

Check Nginx Configuration

docker exec glean-web nginx -t

Check Backend Connection

# Directly access backend API
curl http://localhost:8000/api/health

Cannot Access Admin Dashboard

Check Admin Service

docker compose ps admin
docker compose logs admin

Verify Port

curl http://localhost:3001

Out of Memory

Check Memory Usage

docker stats --no-stream

Solutions

1. Use lite deployment (without Milvus)
2. Increase system memory
3. Set resource limits

docker-compose.yml

services:
  backend:
    deploy:
      resources:
        limits:
          memory: 1G

Disk Space Full

Check Disk Usage

docker system df

Clean Unused Resources

# Clean unused images
docker image prune -a

# Clean unused volumes (be careful not to delete glean volumes)
docker volume prune

# Clean stopped containers
docker container prune

Log Rotation

# Truncate Docker logs
truncate -s 0 $(docker inspect --format='{{.LogPath}}' glean-backend)

Database Issues

Migration Failed

# Check migration logs
docker compose logs backend | grep -i migration

# Manually run migration
docker exec -it glean-backend bash
cd /app && uv run alembic upgrade head

Too Many Database Connections

Check and increase PostgreSQL connection limit:

docker-compose.yml

services:
  postgres:
    command:
      - postgres
      - -c
      - max_connections=200

Milvus Issues (Full Version)

Milvus Won’t Start

# Check Milvus dependency services
docker compose ps milvus-etcd milvus-minio

# Check Milvus logs
docker compose logs milvus

Milvus Out of Memory

Milvus requires significant memory, you can:

1. Increase system memory
2. Use lite deployment mode

Getting Help

If the above methods don’t solve the problem:

1. View Documentation: Glean Docs
2. GitHub Issues: Submit Issue
3. Discord Community: Join Discord

When submitting an Issue, please include:

• Glean version
• Deployment mode (full/lite)
• Error logs
• Reproduction steps