Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/flyio-common-errors/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill flyio-common-errors. Copyright stays with the author (MIT).

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

1. Classify the failure as build, deploy, health, networking, storage, access, rate-limit, or platform availability.
2. Reproduce with the smallest safe probe, then inspect configuration, secret scope, release state, machine health, and region policy.
3. Apply the least disruptive reversible correction and verify recovery plus a safe failure path.
4. 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

• Fly.io Status
• Fly.io Community
• Fly Docs

Next Steps

For comprehensive debugging, see flyio-debug-bundle.