jfraeysd/fetch_ml
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
fetch_ml/docs/src/troubleshooting.md
Jeremie Fraeys 605829dfc3 Update documentation for new features and fix outdated references 
- Update deployment.md to reference new deployments/ directory structure
- Update CLI reference with new multi-user authentication system
- Add roles and permissions examples to configuration
- Fix docker-compose paths in testing documentation
- Remove references to non-existent docker-compose.test.yml
- Update troubleshooting with correct test commands
- Remove misplaced README files from test directories
2025-12-06 13:46:40 -05:00

2.1 KiB
Raw Blame History

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 up -d or make test-auth

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)