{"record":{"id":"79f65ab25079fd00","repo":"kubernetes/kops","slug":"failed-to-connect-to-ssh-agent-with-ssh-auth-sock","errorCode":null,"errorMessage":"failed to connect to SSH agent with SSH_AUTH_SOCK %q: %w","messagePattern":"failed to connect to SSH agent with SSH_AUTH_SOCK %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/commands/toolbox_enroll.go","lineNumber":299,"sourceCode":"func (s *SSHHost) Close() error {\n\tif s.sshClient != nil {\n\t\tif err := s.sshClient.Close(); err != nil {\n\t\t\treturn err\n\t\t}\n\t\ts.sshClient = nil\n\t}\n\treturn nil\n}\n\n// NewSSHHost creates a new SSHHost.\nfunc NewSSHHost(ctx context.Context, host string, sshPort int, sshUser string, sudo bool) (*SSHHost, error) {\n\tsocket := os.Getenv(\"SSH_AUTH_SOCK\")\n\tif socket == \"\" {\n\t\treturn nil, fmt.Errorf(\"cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set\")\n\t}\n\tconn, err := net.Dial(\"unix\", socket)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to connect to SSH agent with SSH_AUTH_SOCK %q: %w\", socket, err)\n\t}\n\n\tagentClient := agent.NewClient(conn)\n\n\tsigners, err := agentClient.Signers()\n\tif err != nil {\n\t\t_ = conn.Close()\n\t\treturn nil, fmt.Errorf(\"failed to get signers: %w\", err)\n\t}\n\n\tif len(signers) == 0 {\n\t\treturn nil, fmt.Errorf(\"SSH agent has no keys\")\n\t}\n\n\tsshConfig := &ssh.ClientConfig{\n\t\tHostKeyCallback: func(hostname string, remote net.Addr, key ssh.PublicKey) error {\n\t\t\tklog.Warningf(\"accepting SSH key %v for %q\", key, hostname)\n\t\t\treturn nil","sourceCodeStart":281,"sourceCodeEnd":317,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/commands/toolbox_enroll.go#L281-L317","documentation":"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).","triggerScenarios":"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.","commonSituations":"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).","solutions":["Check the socket: ls -l $SSH_AUTH_SOCK; if stale, restart: eval $(ssh-agent) && ssh-add","In tmux/screen, update the env: export SSH_AUTH_SOCK=$(ls -t /tmp/ssh-*/agent.* | head -1) and reattach with tmux update-environment","In Docker, mount the socket and set SSH_AUTH_SOCK to the in-container path (or use SSH agent forwarding tooling)","Verify socket permissions allow the current user to connect"],"exampleFix":"// before\n# stale agent socket in tmux pane\nkops toolbox enroll ... # failed to connect to SSH agent with SSH_AUTH_SOCK \"/tmp/ssh-Xq1/agent.1234\"\n// after\nexport SSH_AUTH_SOCK=$(ls -t /tmp/ssh-*/agent.* 2>/dev/null | head -1)\nssh-add -l && kops toolbox enroll ...","handlingStrategy":"validation","validationCode":"sock := os.Getenv(\"SSH_AUTH_SOCK\")\nif fi, err := os.Stat(sock); err != nil || fi.Mode()&os.ModeSocket == 0 {\n    return fmt.Errorf(\"SSH_AUTH_SOCK %q is not a live socket; restart ssh-agent\", sock)\n}\nif c, err := net.Dial(\"unix\", sock); err != nil {\n    return fmt.Errorf(\"cannot connect to agent socket %q: %w\", sock, err)\n} else { c.Close() }","typeGuard":"func agentSocketAlive() bool {\n    s := os.Getenv(\"SSH_AUTH_SOCK\")\n    if s == \"\" { return false }\n    fi, err := os.Stat(s)\n    return err == nil && fi.Mode()&os.ModeSocket != 0\n}","tryCatchPattern":"host, err := NewSSHHost(ctx, hostAddr, port, user, sudo)\nif err != nil && strings.Contains(err.Error(), \"failed to connect to SSH agent\") {\n    return fmt.Errorf(\"agent socket stale; run: eval $(ssh-agent) && ssh-add\")\n}","preventionTips":["In tmux/screen, refresh SSH_AUTH_SOCK after restarting the agent","Mount and path-map agent sockets correctly when using Docker","Check socket permissions match the running user"],"tags":["ssh","ssh-agent","unix-socket"],"backgroundTag":"ssh-agent-unreachable","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T12:17:11.808Z"}