{"record":{"id":"08d83cd5e826b535","repo":"juicedata/juicefs","slug":"unusable-kerberos-principal-s","errorCode":null,"errorMessage":"unusable kerberos principal: %s","messagePattern":"unusable kerberos principal: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/object/hdfs_kerberos.go","lineNumber":65,"sourceCode":"\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"error decoding Base64 encoded data %s\", err)\n\t\t}\n\t\tkt = new(keytab.Keytab)\n\t\terr = kt.Unmarshal(decodedKeytab)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t} else if keytabPath != \"\" {\n\t\tkt, err = keytab.Load(keytabPath)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\tif kt != nil {\n\t\t// e.g. KRB5PRINCIPAL=\"primary/instance@realm\"\n\t\tsp := strings.Split(principal, \"@\")\n\t\tif len(sp) != 2 {\n\t\t\treturn nil, fmt.Errorf(\"unusable kerberos principal: %s\", principal)\n\t\t}\n\t\tusername, realm := sp[0], sp[1]\n\t\tlogger.Infof(\"username: %s, realm: %s\", username, realm)\n\t\tclient := krb.NewWithKeytab(username, realm, kt, cfg, krbSettings...)\n\t\treturn client, nil\n\t}\n\n\t// Determine the ccache location from the environment, falling back to the\n\t// default location.\n\tccachePath := os.Getenv(\"KRB5CCNAME\")\n\tif strings.Contains(ccachePath, \":\") {\n\t\tif strings.HasPrefix(ccachePath, \"FILE:\") {\n\t\t\tccachePath = strings.SplitN(ccachePath, \":\", 2)[1]\n\t\t} else {\n\t\t\treturn nil, fmt.Errorf(\"unusable ccache: %s\", ccachePath)\n\t\t}\n\t} else if ccachePath == \"\" {\n\t\tu, err := user.Current()","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/object/hdfs_kerberos.go#L47-L83","documentation":"When a keytab is provided, getKerberosClient requires KRB5PRINCIPAL in the form \"primary/instance@realm\". It splits the principal at \"@\" and demands exactly two parts. Anything else — missing realm, multiple @ signs, or an empty KRB5PRINCIPAL — fails with \"unusable kerberos principal: %s\". The library needs both the username (primary/instance) and realm to construct the krb5 client.","triggerScenarios":"getKerberosClient called (keytab present) with KRB5PRINCIPAL unset/empty, or set to a short-form principal like \"hdfs/host\" without \"@REALM\", or containing extra \"@\" characters (e.g. escaped or duplicated).","commonSituations":"Using the bare username instead of the full principal; forgetting the realm when the keytab was exported for a multi-realm setup; copying a principal with a trailing comment; KRB5PRINCIPAL simply not set while the keytab is.","solutions":["Set KRB5PRINCIPAL to the full principal exactly as in the keytab, e.g. KRB5PRINCIPAL=\"juicefs/host.example.com@EXAMPLE.COM\".","Confirm the exact principal with klist -kte /path/to/keytab and copy it verbatim (case-sensitive realm).","Remove any stray \"@\" characters or whitespace from the value.","If only a ccache is used (no keytab), clear the keytab env var so the ccache path is taken instead."],"exampleFix":"// before\nexport KRB5PRINCIPAL=\"juicefs\"            # no @realm\n// after\nexport KRB5PRINCIPAL=\"juicefs/host.example.com@EXAMPLE.COM\"","handlingStrategy":"validation","validationCode":"p := os.Getenv(\"KRB5PRINCIPAL\")\nif ktSet := os.Getenv(\"KRB5KEYTAB\") != \"\"; ktSet {\n    parts := strings.Split(p, \"@\")\n    if p == \"\" || len(parts) != 2 || parts[0] == \"\" || parts[1] == \"\" {\n        return fmt.Errorf(\"KRB5PRINCIPAL must be 'primary/instance@REALM', got %q\", p)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"unusable kerberos principal\") {\n    logger.Fatalf(\"Bad KRB5PRINCIPAL: %v — use full principal like user/host@REALM\", err)\n}","preventionTips":["Always use the full principal exactly as listed by klist -kte.","Keep realms uppercase and case-consistent with the keytab.","Template-check the principal format in Helm/Ansible configs.","Never leave KRB5PRINCIPAL empty when a keytab is configured."],"tags":["hdfs","kerberos","principal","configuration"],"backgroundTag":"invalid-argument-format","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}