juanfont/headscale · error

getting docker context: %w

Error message

getting docker context: %w

What it means

Returned by `getCurrentDockerContext` when shelling out to `docker context inspect` fails — the docker CLI is missing from PATH, exited non-zero (no CLI config, invalid current context), or the context deadline hit. This runs to decide client options (e.g. custom host) and socket path handling for the test runner.

Source

Thrown at cmd/hi/docker.go:490

				}
			}
		}
	}

	if len(clientOpts) == 1 {
		clientOpts = append(clientOpts, client.FromEnv)
	}

	return client.NewClientWithOpts(clientOpts...)
}

// getCurrentDockerContext retrieves the current Docker context information.
func getCurrentDockerContext(ctx context.Context) (*DockerContext, error) {
	cmd := exec.CommandContext(ctx, "docker", "context", "inspect")

	output, err := cmd.Output()
	if err != nil {
		return nil, fmt.Errorf("getting docker context: %w", err)
	}

	var contexts []DockerContext
	if err := json.Unmarshal(output, &contexts); err != nil { //nolint:noinlineerr
		return nil, fmt.Errorf("parsing docker context: %w", err)
	}

	if len(contexts) > 0 {
		return &contexts[0], nil
	}

	return nil, ErrNoDockerContext
}

// getDockerSocketPath returns the correct Docker socket path for the current context.
func getDockerSocketPath() string {
	// Always use the default socket path for mounting since Docker handles
	// the translation to the actual socket (e.g., colima socket) internally

View on GitHub (pinned to 565fd254d0)

Solutions

1. Ensure `docker` CLI is installed: `which docker && docker context ls`.
2. Fix or recreate the current context: `docker context create ...` or `docker context use default`.
3. Check DOCKER_CONFIG points to a valid directory with readable config.json.
4. Verify the default docker socket exists when using the default context.

Example fix

# before: broken current context
docker context use deleted-ctx
go run ./cmd/hi run TestX   # -> getting docker context: ...

# after: point at a valid context
docker context use default
go run ./cmd/hi run TestX

// verify docker CLI and context before invoking hi
if err := exec.Command("docker", "context", "ls").Run(); err != nil {
    return fmt.Errorf("docker CLI/context unusable: %w", err)
}

if err := runDockerTest(ctx, config); err != nil {
    if strings.Contains(err.Error(), "getting docker context") {
        // fix CLI install or `docker context use default`, then retry
    }
}

When it happens

Trigger: The `docker` binary is not installed or not on PATH when running `hi`; DOCKER_CONFIG points at a broken config dir; the current context is set to a deleted context; the passed ctx is cancelled.

Common situations: Running `hi` in an environment with only the Docker SDK and no CLI; CI images that install docker CLI late; switching to colima then removing its context; DOCKER_CONFIG env var pointing to a missing directory.

Related errors

• creating Docker client: %w
• ensuring image availability: %w
• creating container: %w
• starting container: %w
• executing test: %w

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