Fly.io Debug Bundle

Overview

Collect machine state, app health, volume status, deploy history, network connectivity, and platform diagnostics into a single archive for Fly.io support tickets. This bundle captures everything needed to troubleshoot stuck deployments, machine boot failures, volume corruption, and edge networking problems.

Prerequisites

An incident owner, secure evidence location, retention deadline, and redaction rules for logs, configuration, tokens, and user data.
An opaque correlation ID and a safe health/read-only probe before collecting broad runtime evidence.

Instructions

Capture version, release, aggregate health, opaque machine identifiers, and relevant configuration references.
Review all logs and generated files for tokens, credentials, request bodies, and personal data before archiving.
Encrypt and restrict the resulting evidence to incident responders, then retire it according to the retention decision.

Output

Create a redacted bundle index with correlation ID, artifact list, access owner, retention date, reproduction result, and next action. Sensitive originals belong only in the approved incident store.

Error Handling

Stop collection and rotate credentials if a secret or sensitive data is found in the bundle.
Record missing diagnostics rather than expanding access or collection without approval.
Escalate possible exposure before continuing normal troubleshooting.

Examples

For a synthetic machine boot failure, retain release ID, opaque machine ID, and aggregate health result. Verify the archive contains no token or request body, grant access only to the incident owner, and delete it when its retention period ends.

Debug Collection Script

#!/bin/bash
set -euo pipefail
APP="${1:?Usage: fly-debug.sh <app-name>}"
BUNDLE="debug-flyio-${APP}-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

# Environment check
echo "=== Fly.io Debug Bundle: $APP ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "FLY_API_TOKEN: ${FLY_API_TOKEN:+[SET]}" >> "$BUNDLE/summary.txt"
echo "flyctl: $(fly version 2>/dev/null || echo 'not found')" >> "$BUNDLE/summary.txt"

# API connectivity
HTTP=$(curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ${FLY_API_TOKEN}" \
  https://api.machines.dev/v1/apps 2>/dev/null || echo "000")
echo "Machines API: HTTP $HTTP" >> "$BUNDLE/summary.txt"

# App status and machine state
fly status -a "$APP" > "$BUNDLE/status.txt" 2>&1 || true
fly machine list -a "$APP" --json > "$BUNDLE/machines.json" 2>&1 || true

# Recent logs (last 200 lines)
fly logs -a "$APP" --no-tail 2>&1 | tail -200 > "$BUNDLE/logs.txt" || true

# Volumes, releases, and doctor
fly volumes list -a "$APP" > "$BUNDLE/volumes.txt" 2>&1 || true
fly releases -a "$APP" > "$BUNDLE/releases.txt" 2>&1 || true
fly doctor > "$BUNDLE/doctor.txt" 2>&1 || true

# Network and platform status
curl -s -o /dev/null -w "App endpoint: HTTP %{http_code}\n" \
  "https://${APP}.fly.dev/" >> "$BUNDLE/summary.txt" 2>/dev/null || echo "App: unreachable" >> "$BUNDLE/summary.txt"
curl -s https://status.flyio.net/api/v2/status.json 2>/dev/null | \
  jq -r '"Platform: " + .status.description' >> "$BUNDLE/summary.txt" || true

tar -czf "$BUNDLE.tar.gz" "$BUNDLE" && rm -rf "$BUNDLE"
echo "Bundle: $BUNDLE.tar.gz"

Analyzing the Bundle

tar -xzf debug-flyio-*.tar.gz
cat debug-flyio-*/summary.txt                 # Quick health overview
jq '.[] | {id, state, region}' debug-flyio-*/machines.json  # Machine states
grep -i "error\|fail\|crash" debug-flyio-*/logs.txt         # Error patterns
cat debug-flyio-*/doctor.txt                  # Fly.io self-diagnosis

Common Issues

Symptom	Check in Bundle	Fix
Machine stuck in `created` state	`machines.json` shows state != `started`	`fly machine start <id>` or destroy and redeploy
Deploy hangs indefinitely	`releases.txt` shows failed release	Check `logs.txt` for health check timeout; increase `[http_service.concurrency]`
Volume not mounting	`volumes.txt` shows volume in wrong region	Create volume in same region as machine; only one machine can mount a volume
App returns 502	`summary.txt` shows app unreachable	Check `logs.txt` for process crash; verify internal port matches `fly.toml`
DNS not resolving	`doctor.txt` shows DNS warnings	Run `fly ips list`; ensure A/AAAA records exist; check custom domain CNAME

Automated Health Check

async function checkFlyio(): Promise<void> {
  const token = process.env.FLY_API_TOKEN;
  if (!token) { console.error("[FAIL] FLY_API_TOKEN not set"); return; }

  const res = await fetch("https://api.machines.dev/v1/apps", {
    headers: { Authorization: `Bearer ${token}` },
  });
  console.log(`[${res.ok ? "OK" : "FAIL"}] Machines API: HTTP ${res.status}`);

  if (res.ok) console.log("[INFO] Machines API accessible");
}
checkFlyio();

Resources

Fly.io Status

Next Steps

See flyio-common-errors.