gabrielmoreira Fly.io Common Errors
Overview
Quick reference for the most common Fly.io deployment and runtime errors with solutions.
Prerequisites
- An authorized operator, opaque correlation ID, redacted logs/metrics, and a known service owner.
- A safe staging/read-only reproduction path; do not use destructive lifecycle actions to diagnose a production issue.
Instructions
- Classify the failure as build, deploy, health, networking, storage, access, rate-limit, or platform availability.
- Reproduce with the smallest safe probe, then inspect configuration, secret scope, release state, machine health, and region policy.
- Apply the least disruptive reversible correction and verify recovery plus a safe failure path.
- Escalate possible secret exposure, data loss, or cross-region integrity issues immediately.
Output
Return a diagnostic receipt with category, opaque correlation ID, reproduction result, corrective action, verification, owner, and follow-up. Exclude tokens, log bodies, configuration secrets, and user data.
Error Handling
- Do not solve permission problems with broader tokens; route them to the authorized owner.
- Quarantine failed deployment or storage operations for review and use bounded retry/backoff.
- Roll back before replaying stateful work after an integrity or health failure.
Examples
Use a synthetic health failure, inspect only redacted release/machine status, restore the prior configuration, and verify readiness. If the issue is a token mismatch, pause automation until the scoped credential is corrected and a read-only check succeeds.
Error Reference
Health Check Failed
Error: health checks for machine e784... failed
Causes: App not listening on correct port, slow startup, missing dependencies.
Fix:
# 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
# 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:
# 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:
# 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:
# Verify target app is running
fly status -a my-api
# Check the app listens on correct port
fly ssh console -a my-api -C "ss -tlnp"
# Ensure apps are in same organization
fly orgs list
Volume Mount Failures
Error: volume vol_xxx not found in region iad
Fix:
# Volume must be in same region as machine
fly volumes list -a my-app # Check region
fly volumes create data --size 10 --region iad # Match region
Rate Limited by Machines API
HTTP 429 Too Many Requests
Fix: Implement backoff. See flyio-rate-limits.
Quick Diagnostic Commands
fly status -a my-app # App and machine status
fly logs -a my-app # Recent logs
fly machine list -a my-app # All machines
fly ssh console -a my-app # Shell access
fly doctor # Check flyctl health
fly platform status # Fly.io platform status
Resources
Next Steps
For comprehensive debugging, see flyio-debug-bundle.