# Troubleshooting

Common issues and solutions for Fetch ML.

## Quick Fixes

### Services Not Starting

```bash
# 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

```bash
# 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

```bash
# 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](development-setup.md))

### 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
```bash
./bin/api-server --version
docker-compose ps
docker-compose logs api-server | grep ERROR
```

## Emergency Reset
```bash
docker-compose down -v
rm -rf data/ results/ *.db
docker-compose up -d (testing only)
```