jesseduffield/lazydocker · error

override DOCKER_HOST to tunneled socket: %w

Error message

override DOCKER_HOST to tunneled socket: %w

What it means

After the ssh tunnel is successfully created, lazydocker rewrites DOCKER_HOST (via os.Setenv through self.setenv) to unix://<localSocket> so the docker client connects through the tunnel. This error means the tunnel itself worked but setting the environment variable failed — an extremely rare environment-level failure chained with %w.

Source

Thrown at pkg/commands/ssh/ssh.go:64

// to point towards a local unix socket tunneled over SSH to the specified ssh host.
func (self *SSHHandler) HandleSSHDockerHost() (io.Closer, error) {
	const key = "DOCKER_HOST"
	ctx := context.Background()
	u, err := url.Parse(self.getenv(key))
	if err != nil {
		// if no or an invalid docker host is specified, continue nominally
		return noopCloser{}, nil
	}

	// if the docker host scheme is "ssh", forward the docker socket before creating the client
	if u.Scheme == "ssh" {
		tunnel, err := self.createDockerHostTunnel(ctx, u.Host)
		if err != nil {
			return noopCloser{}, fmt.Errorf("tunnel ssh docker host: %w", err)
		}
		err = self.setenv(key, tunnel.socketPath)
		if err != nil {
			return noopCloser{}, fmt.Errorf("override DOCKER_HOST to tunneled socket: %w", err)
		}

		return tunnel, nil
	}
	return noopCloser{}, nil
}

type noopCloser struct{}

func (noopCloser) Close() error { return nil }

type tunneledDockerHost struct {
	socketPath string
	cmd        *exec.Cmd
	oSCommand  CmdKiller
}

var _ io.Closer = (*tunneledDockerHost)(nil)

View on GitHub (pinned to 7e7aadc207)

Solutions

1. Look at the %w-chained cause — if it is a mock/test failure, fix the test double rather than the environment.
2. As a workaround, create the tunnel manually with ssh -L and set DOCKER_HOST yourself, bypassing the setenv step.
3. Report a bug if this fires on a normal desktop OS — it indicates an environmental defect worth investigating upstream.

if _, err := sshHandler.LearnDockerHostShim(); err != nil {
    if strings.Contains(err.Error(), "override DOCKER_HOST") {
        // tunnel is up but env write failed: close it and fall back to direct DOCKER_HOST
        // (in practice this only fires from injected test doubles)
    }
}

When it happens

Trigger: createDockerHostTunnel succeeds and self.setenv("DOCKER_HOST", tunnel.socketPath) returns an error. In the real handler setenv is os.Setenv, which essentially never fails on desktop OSes; it can only fail on exotic platforms or if a test double injects a failure.

Common situations: Almost exclusively seen in unit tests where setenv is mocked to fail; hypothetically a broken libc environment on unusual Unix variants. End users should treat this as 'unreachable in practice' and look at the chained error for clarity.

Related errors

• tunnel ssh docker host: %w
• ssh tunneled socket never became available: %w
• create ssh tunnel tmp file: %w
• tunnel docker host over ssh: %w
• Cannot proceed until docker gives us more information about

AI-assisted analysis of jesseduffield/lazydocker@7e7aadc207 (2026-08-15). Data as JSON: /api/errors/0a6ad1a887466928. Report an issue: GitHub.