k3s-io/k3s · error

insufficient PSK bytes

Error message

insufficient PSK bytes

What it means

Thrown during agent/server config setup when the embedded registry (spegel) is enabled and the cluster IPSEC pre-shared key cannot provide enough entropy. controlConfig.IPSECPSK is hex-decoded and must yield at least 32 bytes (256 bits), because spegel uses it as the shared authentication secret for registry-to-registry replication between nodes. A short or misconfigured PSK (e.g. hand-crafted token or trimmed key) fails this length gate before the registry starts.

Source

Thrown at pkg/agent/config/config.go:710

	nodeConfig.AgentConfig.DisableServiceLB = envInfo.DisableServiceLB
	nodeConfig.AgentConfig.VLevel = cmds.LogConfig.VLevel
	nodeConfig.AgentConfig.VModule = cmds.LogConfig.VModule
	nodeConfig.AgentConfig.LogFile = cmds.LogConfig.LogFile
	nodeConfig.AgentConfig.AlsoLogToStderr = cmds.LogConfig.AlsoLogToStderr

	privRegistries, err := registries.GetPrivateRegistries(envInfo.PrivateRegistry)
	if err != nil {
		return nil, err
	}
	nodeConfig.AgentConfig.Registry = privRegistries.Registry

	if nodeConfig.EmbeddedRegistry {
		psk, err := hex.DecodeString(controlConfig.IPSECPSK)
		if err != nil {
			return nil, err
		}
		if len(psk) < 32 {
			return nil, errors.New("insufficient PSK bytes")
		}

		conf := spegel.DefaultRegistry
		conf.ExternalAddress = nodeConfig.AgentConfig.NodeIP
		conf.InternalAddress = controlConfig.Loopback(false)
		conf.RegistryPort = strconv.Itoa(controlConfig.SupervisorPort)
		conf.ClientCAFile = clientCAFile
		conf.ClientCertFile = clientK3sControllerCert
		conf.ClientKeyFile = clientK3sControllerKey
		conf.ServerCAFile = serverCAFile
		conf.ServerCertFile = servingKubeletCert
		conf.ServerKeyFile = servingKubeletKey
		conf.PSK = psk[:32]
		conf.InjectMirror(nodeConfig)
	}

	if err := validateNetworkConfig(nodeConfig); err != nil {
		return nil, err

View on GitHub (pinned to 6ba341e396)

Solutions

1. Use the full cluster token generated by the server: cat /var/lib/rancher/k3s/server/token on the server and pass it via --token on joining nodes
2. If setting the PSK explicitly, generate a 32-byte key: openssl rand -hex 32 (64 hex characters) and use that value
3. Verify the PSK hex-decodes cleanly and is >= 64 hex chars before restarting the node
4. Restart k3s on the server first so a valid PSK is distributed, then restart agents

Example fix

// before
IPSECPSK: "deadbeef" // 4 bytes after hex decode -> insufficient PSK bytes

// after
IPSECPSK: "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" // 32 bytes (openssl rand -hex 32)

psk, err := hex.DecodeString(controlConfig.IPSECPSK)
if err != nil {
    return fmt.Errorf("IPSECPSK is not valid hex: %w", err)
}
if len(psk) < 32 {
    return fmt.Errorf("IPSECPSK must be at least 32 bytes (64 hex chars), got %d bytes", len(psk))
}
// safe to enable embedded registry

if err := agentconfig.Config(ctx, ...); err != nil {
    if strings.Contains(err.Error(), "insufficient PSK bytes") {
        // regenerate token/PSK on the server, redistribute, retry join
    }
    return err
}

When it happens

Trigger: Running a node with --embedded-registry where controlConfig.IPSECPSK hex-decodes to fewer than 32 bytes; passing a custom/shortened cluster token instead of the full generated one; an invalid hex string would instead fail earlier at hex.DecodeString; upgrades where the PSK field was manually edited.

Common situations: Admin copies only part of the node token from /var/lib/rancher/k3s/server/token; someone hand-rolls a k3s.yaml/token with a short secret; CI spinning up clusters with generated-but-short PSKs when enabling the embedded registry mirror.

Related errors

• embedded registry mirror requires embedded containerd
• Flannel configuration not defined
• Initial server URL host is not defined for load balancer
• invalid username/password combination
• --server is required

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/5a625210cf7249eb. Report an issue: GitHub.