{"record":{"id":"5a625210cf7249eb","repo":"k3s-io/k3s","slug":"insufficient-psk-bytes","errorCode":null,"errorMessage":"insufficient PSK bytes","messagePattern":"insufficient PSK bytes","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/config/config.go","lineNumber":710,"sourceCode":"\tnodeConfig.AgentConfig.DisableServiceLB = envInfo.DisableServiceLB\n\tnodeConfig.AgentConfig.VLevel = cmds.LogConfig.VLevel\n\tnodeConfig.AgentConfig.VModule = cmds.LogConfig.VModule\n\tnodeConfig.AgentConfig.LogFile = cmds.LogConfig.LogFile\n\tnodeConfig.AgentConfig.AlsoLogToStderr = cmds.LogConfig.AlsoLogToStderr\n\n\tprivRegistries, err := registries.GetPrivateRegistries(envInfo.PrivateRegistry)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tnodeConfig.AgentConfig.Registry = privRegistries.Registry\n\n\tif nodeConfig.EmbeddedRegistry {\n\t\tpsk, err := hex.DecodeString(controlConfig.IPSECPSK)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t\tif len(psk) < 32 {\n\t\t\treturn nil, errors.New(\"insufficient PSK bytes\")\n\t\t}\n\n\t\tconf := spegel.DefaultRegistry\n\t\tconf.ExternalAddress = nodeConfig.AgentConfig.NodeIP\n\t\tconf.InternalAddress = controlConfig.Loopback(false)\n\t\tconf.RegistryPort = strconv.Itoa(controlConfig.SupervisorPort)\n\t\tconf.ClientCAFile = clientCAFile\n\t\tconf.ClientCertFile = clientK3sControllerCert\n\t\tconf.ClientKeyFile = clientK3sControllerKey\n\t\tconf.ServerCAFile = serverCAFile\n\t\tconf.ServerCertFile = servingKubeletCert\n\t\tconf.ServerKeyFile = servingKubeletKey\n\t\tconf.PSK = psk[:32]\n\t\tconf.InjectMirror(nodeConfig)\n\t}\n\n\tif err := validateNetworkConfig(nodeConfig); err != nil {\n\t\treturn nil, err","sourceCodeStart":692,"sourceCodeEnd":728,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/config/config.go#L692-L728","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","If setting the PSK explicitly, generate a 32-byte key: openssl rand -hex 32 (64 hex characters) and use that value","Verify the PSK hex-decodes cleanly and is >= 64 hex chars before restarting the node","Restart k3s on the server first so a valid PSK is distributed, then restart agents"],"exampleFix":"// before\nIPSECPSK: \"deadbeef\" // 4 bytes after hex decode -> insufficient PSK bytes\n\n// after\nIPSECPSK: \"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\" // 32 bytes (openssl rand -hex 32)","handlingStrategy":"validation","validationCode":"psk, err := hex.DecodeString(controlConfig.IPSECPSK)\nif err != nil {\n    return fmt.Errorf(\"IPSECPSK is not valid hex: %w\", err)\n}\nif len(psk) < 32 {\n    return fmt.Errorf(\"IPSECPSK must be at least 32 bytes (64 hex chars), got %d bytes\", len(psk))\n}\n// safe to enable embedded registry","typeGuard":null,"tryCatchPattern":"if err := agentconfig.Config(ctx, ...); err != nil {\n    if strings.Contains(err.Error(), \"insufficient PSK bytes\") {\n        // regenerate token/PSK on the server, redistribute, retry join\n    }\n    return err\n}","preventionTips":["Never hand-craft the cluster token; always distribute /var/lib/rancher/k3s/server/token","When generating a custom PSK use openssl rand -hex 32 and verify 64+ hex chars","Automate a preflight check that hex-decodes the PSK and asserts len >= 32 before enabling --embedded-registry"],"tags":["security","psk","embedded-registry","spegel","config"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}