flyio-common-errors

# Fly.io Common Errors ## Overview Quick reference for the most common Fly.io deployment and runtime errors with solutions. ## Error Reference ### Health Check Failed ``` Error: health checks for machine e784... failed ``` **Causes:** App not listening on correct port, slow startup, missing dependencies. **Fix:** ```bash # Check logs for startup errors fly logs -a my-app # Verify internal_port matches your app grep internal_port fly.toml # SSH in and test manually fly ssh console -C "curl localhost:3000/health" # Increase health check grace period ``` ```toml # fly.toml — give app more time to start [http_service.checks] grace_period = "30s" interval = "15s" timeout = "5s" ``` ### Deployment Failed — Image Build ``` Error: failed to build: exit code 1 ``` **Fix:** ```bash # Test Docker build locally first docker build -t test . docker run -p 3000:3000 test # Check Dockerfile — common issues: # - Missing EXPOSE directive # - Wrong WORKDIR # - npm install before COPY (layer caching) ``` ### Machine Won't Start ``` Error: machine e784... failed to start ``` **Fix:** ```bash # Check machine events fly machine status e784... # Common cause: OOM — increase memory fly scale vm shared-cpu-1x --memory 512 # Or check for crash loops in logs fly logs --instance e784... ``` ### Connection Refused on .internal ``` Error: connection refused my-api.internal:3000 ``` **Fix:** ```bash # Verify target app is running fly status -a my-api # Check the app listens on c...