docker/cli · warning

timeout waiting for stats

Error message

timeout waiting for stats

What it means

Set by the stats collector goroutine in cli/command/container/stats_helpers.go when no stats sample arrives from the daemon's ContainerStats stream within 2 seconds. The `docker stats` display shows this per-container error state and zeroes the row's values; it also releases the wait group so a slow container cannot hang the whole table. It indicates a slow or stalled stats stream, not necessarily a dead container.

Source

Thrown at cli/command/container/stats_helpers.go:154

					NetworkRx:        netRx,
					NetworkTx:        netTx,
					BlockRead:        float64(blkRead),
					BlockWrite:       float64(blkWrite),
					PidsCurrent:      v.PidsStats.Current,
				})
			}
			u <- nil
			if !streamStats {
				return
			}
		}
	}()
	for {
		select {
		case <-time.After(2 * time.Second):
			// zero out the values if we have not received an update within
			// the specified duration.
			s.SetErrorAndReset(errors.New("timeout waiting for stats"))
			// if this is the first stat you get, release WaitGroup
			if !getFirst {
				getFirst = true
				waitFirst.Done()
			}
		case err := <-u:
			s.SetError(err)
			if errors.Is(err, io.EOF) {
				return
			}
			if err != nil {
				continue
			}
			// if this is the first stat you get, release WaitGroup
			if !getFirst {
				getFirst = true
				waitFirst.Done()
			}

View on GitHub (pinned to e9452d6e78)

Solutions

1. Check daemon health and load on the Docker host (top, dockerd/containerd logs) — the stream is stalling server-side
2. If using a remote DOCKER_HOST/context, test latency and retry locally; slow links routinely miss the 2s window
3. Limit scope to fewer containers: docker stats ctr1 ctr2 instead of streaming everything
4. Try a one-shot snapshot with docker stats --no-stream to see whether any sample arrives at all
5. Restart dockerd/containerd if a specific container's stats stream is permanently wedged

When it happens

Trigger: The select's 2-second time.After fires before a decoded stats message lands on the update channel: daemon under heavy load, containers on a slow/remote DOCKER_HOST connection, a very large number of containers being streamed at once, a paused/wedged containerd shim, or cgroup stats collection stalling on the host.

Common situations: Remote daemons over high-latency links (ssh:// or TCP contexts); hosts under CPU/IO pressure where cgroup reads are slow; rootless or VM-based setups (Docker Desktop) with an overloaded VM; huge fleets where `docker stats` with no arguments streams hundreds of containers.

Related errors

• filtering is not supported when specifying a list of contain
• conflicting options: cannot specify both --network-alias and
• valid streams are STDIN, STDOUT and STDERR
• container prune has been cancelled
• containers prune has been cancelled

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/4cd8695031d8442f.json. Report an issue: GitHub.