What causes "parsing docker context: %w" in juanfont/headscale?

Run `docker context inspect` manually and check whether output is `[{...}]` or `{...}`.

parsing docker context: %w

Error message

parsing docker context: %w

What it means

Returned by `getCurrentDockerContext` when `docker context inspect` succeeded but its stdout was not valid JSON matching []DockerContext. The docker CLI usually emits a single object unless `-f` is set, so shape/type mismatches are the classic cause; older/newer CLI output format changes can also break the unmarshal.

Source

Thrown at cmd/hi/docker.go:495

	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
	return "/var/run/docker.sock"
}

// checkImageAvailableLocally checks if the specified Docker image is available locally.
func checkImageAvailableLocally(ctx context.Context, cli *client.Client, imageName string) (bool, error) {

View on GitHub (pinned to 565fd254d0)

Solutions

Run `docker context inspect` manually and check whether output is `[{...}]` or `{...}`.
Upgrade/downgrade docker CLI to a mainstream version (or the one pinned in the repo's nix shell).
Remove any shell wrappers/aliases that alter docker output.
As a workaround, `docker context use default` — the default context path avoids the inspect dependency.

Defensive patterns

Strategy: validation

Validate before calling

// pre-validate the inspect output shape
out, err := exec.Command("docker", "context", "inspect").Output()
if err != nil {
    return err
}
if len(out) > 0 && out[0] != '[' {
    out = append([]byte{'['}, append(out, ']')...) // normalize object -> array
}
var ctxs []DockerContext
return json.Unmarshal(out, &ctxs)

Try / catch

if err := getCurrentDockerContext(ctx); err != nil {
    if strings.Contains(err.Error(), "parsing docker context") {
        // CLI output shape mismatch: pin a mainstream docker CLI version or
        // `docker context use default` to bypass the inspect path
    }
}

Prevention

Use the repo's nix-developed toolchain, which pins a known docker CLI.
Avoid shell wrappers that alter docker output.
Run `docker context inspect` manually after CLI upgrades to confirm array output.

When it happens

Trigger: CLI version that prints an object instead of an array (or vice versa); localized or otherwise modified CLI output; empty-but-zero-exit output; fields whose JSON types don't match the DockerContext struct.

Common situations: Upgrading the docker CLI to a version with changed context inspect output; wrapper scripts that prepend output to docker; unusual DOCKER_CONFIG JSON.

Related errors

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