timeout waiting for container %s to restart and become ready

Error message

timeout waiting for container %s to restart and become ready: %w

What it means

Error "timeout waiting for container %s to restart and become ready: %w" thrown in juanfont/headscale.

Source

Thrown at integration/tsic/tsic.go:803

	// Use Docker API to restart the container
	err := t.pool.Client.RestartContainer(t.container.Container.ID, 30)
	if err != nil {
		return fmt.Errorf("restarting container %s: %w", t.hostname, err)
	}

	// Wait for the container to be back up and tailscaled to be ready
	// We use exponential backoff to poll until we can successfully execute a command
	_, err = backoff.Retry(context.Background(), func() (struct{}, error) {
		// Try to execute a simple command to verify the container is responsive
		_, _, err := t.Execute([]string{tailscaleBin, "version"}, dockertestutil.ExecuteCommandTimeout(5*time.Second))
		if err != nil {
			return struct{}{}, fmt.Errorf("container not ready: %w", err)
		}

		return struct{}{}, nil
	}, backoff.WithBackOff(backoff.NewExponentialBackOff()), backoff.WithMaxElapsedTime(30*time.Second))
	if err != nil {
		return fmt.Errorf("timeout waiting for container %s to restart and become ready: %w", t.hostname, err)
	}

	return nil
}

// Up runs `tailscale up` with no arguments.
func (t *TailscaleInContainer) Up() error {
	command := []string{
		tailscaleBin,
		"up",
	}

	if _, _, err := t.Execute(command, dockertestutil.ExecuteCommandTimeout(dockerExecuteTimeout)); err != nil { //nolint:noinlineerr
		return fmt.Errorf(
			"%s failed to bring tailscale client up (%s): %w",
			t.hostname,
			strings.Join(command, " "),
			err,

View on GitHub (pinned to 565fd254d0)

Solutions

Inspect the wrapped error for the underlying cause and correct the failing condition (timeout waiting for container to restart and become ready); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (timeout waiting for container  to restart and become ready); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at integration/tsic/tsic.go:803 when the library encounters an invalid state.

Common situations: Timed out waiting for the container to restart and become ready. Increase the timeout or investigate why tailscaled startup is slow.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/7cf770d62e60428f. Report an issue: GitHub.