kubernetes/kops · error

failed to connect to SSH agent with SSH_AUTH_SOCK %q: %w

Error message

failed to connect to SSH agent with SSH_AUTH_SOCK %q: %w

What it means

SSH_AUTH_SOCK was set but net.Dial("unix", socket) could not connect to the agent socket, meaning the file exists as a setting but no agent is listening there (stale socket from a dead agent, wrong path, or permission denied on the socket).

Source

Thrown at pkg/commands/toolbox_enroll.go:299

func (s *SSHHost) Close() error {
	if s.sshClient != nil {
		if err := s.sshClient.Close(); err != nil {
			return err
		}
		s.sshClient = nil
	}
	return nil
}

// NewSSHHost creates a new SSHHost.
func NewSSHHost(ctx context.Context, host string, sshPort int, sshUser string, sudo bool) (*SSHHost, error) {
	socket := os.Getenv("SSH_AUTH_SOCK")
	if socket == "" {
		return nil, fmt.Errorf("cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set")
	}
	conn, err := net.Dial("unix", socket)
	if err != nil {
		return nil, fmt.Errorf("failed to connect to SSH agent with SSH_AUTH_SOCK %q: %w", socket, err)
	}

	agentClient := agent.NewClient(conn)

	signers, err := agentClient.Signers()
	if err != nil {
		_ = conn.Close()
		return nil, fmt.Errorf("failed to get signers: %w", err)
	}

	if len(signers) == 0 {
		return nil, fmt.Errorf("SSH agent has no keys")
	}

	sshConfig := &ssh.ClientConfig{
		HostKeyCallback: func(hostname string, remote net.Addr, key ssh.PublicKey) error {
			klog.Warningf("accepting SSH key %v for %q", key, hostname)
			return nil

View on GitHub (pinned to 4c8573c808)

Solutions

  1. Check the socket: ls -l $SSH_AUTH_SOCK; if stale, restart: eval $(ssh-agent) && ssh-add
  2. In tmux/screen, update the env: export SSH_AUTH_SOCK=$(ls -t /tmp/ssh-*/agent.* | head -1) and reattach with tmux update-environment
  3. In Docker, mount the socket and set SSH_AUTH_SOCK to the in-container path (or use SSH agent forwarding tooling)
  4. Verify socket permissions allow the current user to connect

Example fix

// before
# stale agent socket in tmux pane
kops toolbox enroll ... # failed to connect to SSH agent with SSH_AUTH_SOCK "/tmp/ssh-Xq1/agent.1234"
// after
export SSH_AUTH_SOCK=$(ls -t /tmp/ssh-*/agent.* 2>/dev/null | head -1)
ssh-add -l && kops toolbox enroll ...
Defensive patterns

Strategy: validation

Validate before calling

sock := os.Getenv("SSH_AUTH_SOCK")
if fi, err := os.Stat(sock); err != nil || fi.Mode()&os.ModeSocket == 0 {
    return fmt.Errorf("SSH_AUTH_SOCK %q is not a live socket; restart ssh-agent", sock)
}
if c, err := net.Dial("unix", sock); err != nil {
    return fmt.Errorf("cannot connect to agent socket %q: %w", sock, err)
} else { c.Close() }

Type guard

func agentSocketAlive() bool {
    s := os.Getenv("SSH_AUTH_SOCK")
    if s == "" { return false }
    fi, err := os.Stat(s)
    return err == nil && fi.Mode()&os.ModeSocket != 0
}

Try / catch

host, err := NewSSHHost(ctx, hostAddr, port, user, sudo)
if err != nil && strings.Contains(err.Error(), "failed to connect to SSH agent") {
    return fmt.Errorf("agent socket stale; run: eval $(ssh-agent) && ssh-add")
}

Prevention

When it happens

Trigger: os.Getenv("SSH_AUTH_SOCK") points to a socket whose agent process exited, a forwarded socket that died after the parent SSH session closed, or a socket the current user cannot access.

Common situations: Reconnecting to a tmux/screen session started before the agent; Docker container inheriting a host socket path that doesn't exist inside the container; agent started under a different user (root vs user).

Related errors

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/79f65ab25079fd00. Report an issue: GitHub.