{"record":{"id":"d81da37822aae4b3","repo":"kubernetes/kops","slug":"cannot-connect-to-ssh-agent-ssh-auth-sock-env-var","errorCode":null,"errorMessage":"cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set","messagePattern":"cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/commands/toolbox_enroll.go","lineNumber":295,"sourceCode":"\tsudo      bool\n}\n\n// Close closes the connection.\nfunc (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","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/commands/toolbox_enroll.go#L277-L313","documentation":"NewSSHHost found the SSH_AUTH_SOCK environment variable empty, so it cannot connect to an ssh-agent to obtain signers; the enroll workflow deliberately requires agent-based key access rather than reading raw key files.","triggerScenarios":"Running kops toolbox enroll in an environment where the SSH_AUTH_SOCK environment variable is not set (or empty) — e.g. non-interactive shell, cron, CI runner, or sudo -E not preserving the env.","commonSituations":"Running kops via sudo without -E, running inside Docker/CI without forwarding the agent, or on a machine where no ssh-agent is running at all (no SSH_AUTH_SOCK exported).","solutions":["Start an agent and add keys: eval $(ssh-agent) && ssh-add","Run kops in a shell that has SSH_AUTH_SOCK set (check: echo $SSH_AUTH_SOCK)","If using sudo, preserve the env: sudo -E kops toolbox enroll ...","Use agent forwarding when connecting from a jump host: ssh -A"],"exampleFix":"// before\n$ sudo kops toolbox enroll ...\nError: cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set\n// after\n$ eval $(ssh-agent) && ssh-add ~/.ssh/id_ed25519\n$ sudo -E kops toolbox enroll ...   # -E preserves SSH_AUTH_SOCK","handlingStrategy":"validation","validationCode":"if os.Getenv(\"SSH_AUTH_SOCK\") == \"\" {\n    return fmt.Errorf(\"SSH_AUTH_SOCK not set; run 'eval $(ssh-agent)' and 'ssh-add' first\")\n}","typeGuard":"func sshAgentAvailable() bool { return os.Getenv(\"SSH_AUTH_SOCK\") != \"\" }","tryCatchPattern":"host, err := NewSSHHost(ctx, hostAddr, port, user, sudo)\nif err != nil {\n    if strings.Contains(err.Error(), \"SSH_AUTH_SOCK\") {\n        return fmt.Errorf(\"start an SSH agent first: eval $(ssh-agent) && ssh-add\")\n    }\n    return err\n}","preventionTips":["Verify echo $SSH_AUTH_SOCK before running enroll","Use sudo -E to preserve agent env through sudo","In CI, start an agent and inject keys before invoking kops"],"tags":["ssh","ssh-agent","environment"],"backgroundTag":"missing-env-var","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"}