Skip to content

Troubleshooting

Common issues and solutions for Fetch ML.

Quick Fixes

Services Not Starting

# Check Docker status
docker-compose ps

# Restart services
docker-compose down && docker-compose up -d (testing only)

# Check logs
docker-compose logs -f

API Not Responding

# Check health endpoint
curl http://localhost:9101/health

# Check if port is in use
lsof -i :9101

# Kill process on port
kill -9 $(lsof -ti :9101)

Database Issues

# Check database connection
docker-compose exec postgres psql -U postgres -d fetch_ml

# Reset database
docker-compose down postgres
docker-compose up -d (testing only) postgres

# Check Redis
docker-compose exec redis redis-cli ping

Common Errors

Authentication Errors

  • Invalid API key: Check config and regenerate hash
  • JWT expired: Check jwt_expiry setting

Database Errors

  • Connection failed: Verify database type and connection params
  • No such table: Run migrations with --migrate (see Development Setup)

Container Errors

  • Runtime not found: Set runtime: docker (testing only) in config
  • Image pull failed: Check registry access

Performance Issues

  • High memory: Adjust resources.memory_limit
  • Slow jobs: Check worker count and queue size

Development Issues

  • Build fails: go mod tidy and cd cli && rm -rf zig-out zig-cache
  • Tests fail: Start test dependencies with docker-compose -f docker-compose.test.yml up -d

CLI Issues

  • Not found: cd cli && zig build dev
  • Connection errors: Check --server and --api-key

Network Issues

  • Port conflicts: lsof -i :9101 and kill processes
  • Firewall: Allow ports 9101, 6379, 5432

Configuration Issues

  • Invalid YAML: python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"
  • Missing fields: Run see [Configuration Schema](configuration-schema.md)

Debug Information

./bin/api-server --version
docker-compose ps
docker-compose logs api-server | grep ERROR

Emergency Reset

docker-compose down -v
rm -rf data/ results/ *.db
docker-compose up -d (testing only)