From flyio-pack
Diagnoses and fixes common Fly.io errors including deployment failures, health check failures, machine issues, and networking problems.
npx claudepluginhub jeremylongshore/claude-code-plugins-plus-skills --plugin flyio-packThis skill is limited to using the following tools:
Quick reference for the most common Fly.io deployment and runtime errors with solutions.
Provides quick reference for Fly.io PaaS deployments including fly.toml config, global distribution, scaling patterns, secrets management, health checks, and troubleshooting. Auto-loads on fly.toml detection.
Deploys and manages Fly.io apps using Docker containers, Fly Machines, fly.toml configs, databases, volumes, secrets. Supports fly launch/deploy, debugging, multi-region setups for Python/Node/Rails/Django apps.
Monitors Fly.io machine states via API polling, implements Express health checks, processes logs, and automates deployment alerts.
Share bugs, ideas, or general feedback.
Quick reference for the most common Fly.io deployment and runtime errors with solutions.
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"
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)
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...
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
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
HTTP 429 Too Many Requests
Fix: Implement backoff. See flyio-rate-limits.
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
For comprehensive debugging, see flyio-debug-bundle.