Support playbook

How to help a Fly.io customer who is stuck: what to ask first, a table of the twelve failures that account for most tickets (with the command to diagnose and the docs page that fixes it), what each support plan includes, where to escalate, and a reply template that cites the docs. Everything here is advice built on cited facts; where the sources do not settle something it is flagged [verify].

This page is drawn from https://fly.io/docs/getting-started/troubleshooting/, https://fly.io/docs/monitoring/error-codes/, https://fly.io/docs/about/support/, https://fly.io/support, https://fly.io/docs/apps/trouble-host-unavailable/, https://fly.io/docs/reference/health-checks/ and live community.fly.io threads fetched 2026-11-04.

Triage order

Work from the widest scope to the narrowest. Most “my app is broken” reports are one of: the platform, a host, a deploy, or the app itself.

flowchart TD
  A[Customer reports a problem] --> B{Status page or dashboard<br/>shows an incident?}
  B -- yes --> C[Confirm region and host, share the link, advise redundancy]
  B -- no --> D{Did it start after a deploy?}
  D -- yes --> E[Deploy path: logs, fly.toml, health checks, listen address]
  D -- no --> F{Machines started?}
  F -- no --> G[Machine state: restart, OOM, host unavailable]
  F -- yes --> H[Routing and app: error code, checks, DNS, certs]

1. Check platform health first: the status page (https://status.flyio.net) is the place for platform-wide issues, and the dashboard shows host-level issues that might affect an app (https://fly.io/docs/about/support/).
2. Host issues are not posted on the main status page: “We don’t post individual host issues to our main status page because a host issue usually affects a small number of users in a single region” is the docs’ reasoning, and affected customers get a notice on the Status page in their dashboard (https://fly.io/docs/apps/trouble-host-unavailable/). So a green public status page does not rule out a host problem.
3. The docs’ own “try this first” list is: update flyctl (fly version update), run fly doctor, validate fly.toml with fly config validate, watch fly logs, and fly ssh console in (https://fly.io/docs/getting-started/troubleshooting/).

The first five questions

Ask for these in one message so the customer answers once. They match what Fly’s own support page asks customers to include in a ticket (https://fly.io/docs/about/support/).

1. App name and organization.
2. Region(s) and, if they know it, the Machine ID (fly machine list).
3. Output of fly status, fly logs (with UTC timestamps) and fly doctor. Ask for plain text, not screenshots (https://fly.io/docs/about/support/).
4. What changed: a recent fly deploy, a fly.toml edit, a secret change, a scale command.
5. What they expected versus what happened, with the exact error text or proxy error code (for example PR01, PC05, PM03; the full list is at https://fly.io/docs/monitoring/error-codes/).

Tip from the support page: prefixing any flyctl command with LOG_LEVEL=debug shows the lower-level API calls (https://fly.io/docs/about/support/).

Common failures

Facts behind the rows, each from the docs:

• Apps must listen on “0.0.0.0” at the internal_port; frameworks that default to localhost (Rails, Django, Next.js are named) need the host set explicitly (https://fly.io/docs/getting-started/troubleshooting/).
• A failing health check stops routing to the Machine but does not restart or stop it: “your Machines won’t automatically restart or stop due to failing their health checks” (https://fly.io/docs/reference/health-checks/).
• PR01 “No healthy machines” has four named causes: restart retries exhausted by boot errors, failing deployments with volumes, the immediate deploy strategy, and concurrency limits reached (https://fly.io/docs/monitoring/error-codes/).
• When all Machines are scaled to zero, the size resets to shared-cpu-1x with 256MB, so re-size when scaling back up (https://fly.io/docs/apps/trouble-host-unavailable/).
• Placement can fail, and “it’s on you to retry requests” when using the Machines API or flyctl at that level of control (https://fly.io/docs/machines/overview/).
• The Machines API limit is “1 request, per second, per action” with a burst up to 3 req/s (https://fly.io/docs/machines/api/working-with-machines-api/).
• Raw TCP over shared IPv4 does not work; allocate a dedicated IPv4 with fly ips allocate-v4 or use .internal addresses (https://fly.io/docs/getting-started/troubleshooting/).
• Volume corruption (unable to read superblock) is recoverable only from a snapshot; the docs say to always enable snapshots (https://fly.io/docs/getting-started/troubleshooting/).

Plans and what each includes

Support has four doors. Verified on https://fly.io/support on 2026-11-04.

• Paid plans give an organization-specific address, typically <org-name>@support.fly.io, plus the Support Portal in the dashboard; Managed Postgres customers also get Portal access for MPG issues (https://fly.io/docs/about/support/).
• Billing and account questions go to billing@fly.io (https://fly.io/docs/about/support/).
• Published results, 30-day email metrics: “100%” of response-time promises kept, median ticket answered in “1h 12m”, “97.0%” of surveyed customers positive (https://fly.io/support). These move; re-read the page before quoting them.
• Scope: supported products include Networking, Machines, Managed Postgres, Apps, Launch/Deploy, Volumes, Security, Accounts and Billing, Extensions and Monitoring. Not supported: LiteFS and Unmanaged Postgres. Support also cannot debug the customer’s own code or framework (https://fly.io/docs/about/support/).

Escalation path

1. Self-serve: troubleshooting page and error-codes page (links above).
2. Community forum post, with the five answers above. Staff reply there too (example: a host-down thread answered “It was purely a host problem in this case”, https://community.fly.io/t/machine-stuck-in-stopping-on-sin-host-start-restart-kill-return-408-vm-cpu-starved-no-incident-posted/28962).
3. Paid email or Support Portal ticket for anything account-specific, sensitive or urgent; Fly staff say support plan tickets “are given priority over other channels” (https://community.fly.io/t/fly-io-support-community-vs-email-2026-edition-read-this-first/27768).
4. Premium urgent (1 hour) or Enterprise emergency (15 minutes, 24x7) when production is down (https://fly.io/support).
5. Inside Fly, how a ticket reaches engineering is not documented publicly [verify].

Customer reply template

Use plain text, name the evidence, cite the page, give one next step.

Hi NAME,

Thanks for the detail. From the fly status output, Machine MACHINE_ID in REGION shows STATE, and your logs at TIMESTAMP_UTC show ERROR_OR_CODE.

That error means CAUSE (https://fly.io/docs/monitoring/error-codes/). The usual fix is FIX, described at DOCS_URL.

Please try: COMMAND. If it does not clear, reply with the output of fly status, fly logs around the failure (UTC) and fly checks list, and we will look at the host side.

One more thing: this app runs on a single Machine, so a host problem takes it down. The docs recommend at least two (https://fly.io/docs/blueprints/resilient-apps-multiple-machines/).

Say: “I can see X in your output” before “you should do Y”. Do not promise a root cause until the host has been checked; host issues are not on the public status page (https://fly.io/docs/apps/trouble-host-unavailable/).