Fix “context deadline exceeded” in Docker and fly deploy

context deadline exceeded

You usually see this at the end of a long error line. fly deploy prints Building image, sits still for a while, then fails. The words come from Go’s standard library, and they mean one thing: a call had a deadline, and the deadline passed before the call finished.

The message on its own never tells you what to fix. The text in front of it names the call that gave up, and that call is what you fix. On Fly.io a common cause is flyctl trying to reach a Docker daemon on a remote builder over Fly’s private WireGuard network.

What “context deadline exceeded” is telling you

In Go, a context carries a deadline down a chain of function calls. The context package docs say a context with a deadline is cancelled once the deadline passes. From then on, ctx.Err() returns context.DeadlineExceeded, and that error prints as context deadline exceeded. Go returns a separate error when code cancels a context on purpose, so this exact text always means a timer ran out.

That tells you three things:

• The client gave up. The machine that printed the error stopped waiting. The other end may never have received the request.
• The deadline passed first. The error records only that time ran out. Likely reasons are dropped packets, a tunnel that never came up, or a service that is hung.
• Start with the path. Look at the network between you and the daemon, or at the daemon itself, before you look at your app.

A failing Dockerfile looks different. Fly’s troubleshooting guide says a build that fails with exit code: 1 is your Dockerfile, and that docker build . reproduces it locally. If you see context deadline exceeded after a prefix about connecting to Docker, a likely reading is that the build never got going.

Find the step that timed out from the text before it

flyctl wraps the Go error in a chain of prefixes. Read the line from the left: each prefix is one layer that failed because the layer under it timed out. Two shapes cover most fly deploy failures.

flyctl could not finish connecting to the builder:

Error failed to fetch an image or build from source: error connecting to docker: failed building options: failed probing "<app>": context deadline exceeded

error connecting to docker means flyctl was still setting up its connection to the Docker daemon on the remote builder. You may also see a warning that the remote builder heartbeat failed to start. That warning comes from the same timeout.

flyctl had an address but the Docker API never answered:

Error failed to fetch an image or build from source: error fetching docker server info: Get "http://[fdaa:...]:2375/v1.41/info": context deadline exceeded

The address starting fdaa is on Fly’s private network. Port 2375 is Docker’s default port for the remote API without TLS (2376 with TLS), as the Docker remote access docs describe. flyctl sent a request to the builder’s Docker daemon through the tunnel, and no reply came back in time.

Both shapes point at the path between your machine and the builder. The causes below are a suggested order to check them in.

Cause 1: the WireGuard tunnel to Fly’s private network can’t get through

Remote builds are reached over Fly’s private network, and flyctl joins that network through a WireGuard gateway. The flyctl pull request that adds token-mode WireGuard describes the two existing modes:

• Regular mode: flyctl talks WireGuard directly to the gateway on UDP port 51820.
• Websockets mode: flyctl opens a websocket over TLS on TCP port 443, and the gateway forwards WireGuard packets between the websocket and its own UDP socket.

If your network drops outbound UDP on 51820, regular mode can’t bring the tunnel up, and requests to the builder’s fdaa address can wait until the deadline passes. The fly deploy reference lists two flags for this path: --https-failover, on by default, falls back to plain HTTPS to the remote builder if WireGuard fails, and --wg, also true by default, decides whether builder traffic goes over WireGuard or plain HTTPS.

How to tell it is the tunnel

Run the diagnostics Fly recommends first:

fly doctor
fly doctor -o your-org -v

According to the fly doctor reference, fly doctor checks WireGuard, IPs and Docker. -o sets the organisation for the WireGuard tests (it defaults to personal) and -v prints extra detail. If the WireGuard check fails while the rest pass, the tunnel is your problem. For the full sequence during a deploy, run it with debug logging:

LOG_LEVEL=debug fly deploy

Fix it

1. Update flyctl. Fly’s troubleshooting guide warns that outdated versions cause odd failures.

   fly version update

2. Move the tunnel to TCP 443 with fly wireguard websockets:

   fly wireguard websockets enable

3. Run fly doctor again. The WireGuard check should pass now.

4. Deploy again with fly deploy. To send builder traffic over plain HTTPS for this deploy, add --wg=false:

   fly deploy --wg=false

5. If it still times out, reset the WireGuard peer for your organisation. The fly wireguard commands include list, remove and reset:

   fly wireguard list
   fly wireguard reset

On office networks, VPNs and CI runners that allow HTTPS out and little else, websockets mode or --wg=false is a sensible first thing to try.

Cause 2: your peer is pinned to a gateway that has gone down

This cause looks like cause 1, except it appears suddenly on a network where deploys worked yesterday. The same flyctl pull request explains why it happens. Both WireGuard modes register a peer through Fly’s central API in iad. A peer is set up for one specific gateway, and if that gateway goes down, the peer is not moved to another one. Neither the central API nor flyctl knows whether a gateway is healthy.

So a single gateway outage can leave your tunnel pointing at nothing. Your network is fine, and your app is running fine, but every deploy times out.

Fix it

1. Check status.flyio.net for an active incident.

2. Reset the peer so flyctl registers a fresh one:

   fly wireguard reset
   fly doctor

3. If you need to ship before the tunnel recovers, build on your own machine (see cause 3).

The token-mode gateway in that pull request was merged on 25 September 2026 and aims at this failure. It runs on Fly’s edge servers behind an anycast IP and listens only for websocket connections on 443. It checks your token against a nearby auth replica and sets up the peer on the local edge. When one edge goes down, traffic moves to another. Whether it is in a flyctl release yet is unconfirmed: the pull request notes the production gateway still needed a deploy. Keep flyctl updated.

Cause 3: the remote builder is stuck or the build service is having trouble

Sometimes the tunnel is fine and the builder is what has stalled. Fly’s troubleshooting guide says remote builds use Depot, and that fly deploy hangs when Depot has problems. A hang that ends in a timeout prints this same error.

Fix it, from least to most change

1. Use the legacy remote builder. The build still runs remotely but skips Depot:

   fly deploy --depot=false

2. Build on your own machine. This needs Docker installed locally. The upload is slower, but nothing depends on remote build infrastructure:

   fly deploy --local-only

3. Take the build out of the deploy completely. Build and push the image wherever you like, then deploy it. The builders reference describes the image option, which skips the build step:

   fly deploy --image registry.example.com/my-app:1.4.2

If --depot=false works and plain fly deploy doesn’t, check the status page before you change anything else. Fly notes that Docker Hub pulls go through its caching proxy. Images on other registries, such as GitHub Container Registry, skip that cache and can hit rate limits. That failure prints too many requests, so you can tell it apart from a timeout.

Cause 4: building locally and your own Docker daemon is not answering

Once you switch to --local-only, the far end of the call is your own Docker daemon, and the same timeout can come from there.

How to tell it is the local daemon

docker info
docker build .

If docker info hangs or fails, flyctl can’t reach the daemon either. By default the daemon listens on a Unix socket for local clients. If you set it up to listen on TCP, the Docker remote access docs show how to confirm the listener:

$ sudo netstat -lntp | grep dockerd
tcp        0      0 127.0.0.1:2375          0.0.0.0:*               LISTEN      3758/dockerd

The same docs warn that a systemd override and a hosts entry in daemon.json conflict and stop Docker from starting. Use only one of them.

When the daemon can’t pull base images behind a proxy

If the build starts but times out pulling the base image, the daemon may need your company proxy. The Docker daemon proxy docs recommend setting it in daemon.json:

{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "*.test.example.com,.example.org,127.0.0.0/8"
  }
}

Then restart the daemon:

sudo systemctl restart docker

Docker Desktop ignores proxy settings in daemon.json. Set them in Docker Desktop’s own proxy settings.

Keeping deploys from timing out again

The causes above repeat, so make the checks part of how you deploy.

• Run a preflight in CI. Update flyctl, force websockets mode, and fall back to other builders before you call the deploy failed:

  #!/bin/sh
  # deploy.sh
  set -u
  fly version update
  fly wireguard websockets enable
  fly doctor || echo "fly doctor reported a problem, continuing to deploy" >&2
  if ! LOG_LEVEL=debug fly deploy 2> deploy.log; then
    echo "Remote build failed, retrying with the legacy builder" >&2
    fly deploy --depot=false || fly deploy --local-only
  fi

  Save deploy.log as a CI artifact. The prefix before context deadline exceeded tells you which layer failed, and you won’t get that information back once the runner is gone.

• Build images outside the deploy. If your CI already builds and pushes images, deploy with --image. A builder outage then can’t block a release.

• Watch the status page. Subscribe to status.flyio.net so you hear about a gateway or builder incident before you start resetting your own setup.

• Track how often the fallback runs. Count the deploys that needed --depot=false or --local-only. If that count rises, the remote path is getting worse, and you’ll know before it fails outright.

Running on Fly.io? See how Polylane monitors Fly.io in production.