cannot connect to SSH agent; SSH_AUTH_SOCK env variable not

Error message

cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set

What it means

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.

Source

Thrown at pkg/commands/toolbox_enroll.go:295

	sudo      bool
}

// Close closes the connection.
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")
	}

View on GitHub (pinned to 4c8573c808)

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

Example fix

// before
$ sudo kops toolbox enroll ...
Error: cannot connect to SSH agent; SSH_AUTH_SOCK env variable not set
// after
$ eval $(ssh-agent) && ssh-add ~/.ssh/id_ed25519
$ sudo -E kops toolbox enroll ...   # -E preserves SSH_AUTH_SOCK

Defensive patterns

Strategy: validation

Validate before calling

if os.Getenv("SSH_AUTH_SOCK") == "" {
    return fmt.Errorf("SSH_AUTH_SOCK not set; run 'eval $(ssh-agent)' and 'ssh-add' first")
}

Type guard

func sshAgentAvailable() bool { return os.Getenv("SSH_AUTH_SOCK") != "" }

Try / catch

host, err := NewSSHHost(ctx, hostAddr, port, user, sudo)
if err != nil {
    if strings.Contains(err.Error(), "SSH_AUTH_SOCK") {
        return fmt.Errorf("start an SSH agent first: eval $(ssh-agent) && ssh-add")
    }
    return err
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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