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.