{"record":{"id":"eb602d8b157b75d0","repo":"t8y2/dbx","slug":"kerberos-keytab-s-contains-d-principals-configu","errorCode":null,"errorMessage":"Kerberos keytab %s contains %d principals; configure kerberosprincipal explicitly","messagePattern":"Kerberos keytab (.+?) contains (.+?) principals; configure kerberosprincipal explicitly","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/cassandra-go/kerberos.go","lineNumber":577,"sourceCode":"\t\trealm = strings.TrimSpace(defaultRealm)\n\t}\n\tif realm == \"\" {\n\t\treturn \"\", \"\", fmt.Errorf(\"Kerberos realm is required for principal %s\", principal)\n\t}\n\treturn value, realm, nil\n}\n\nfunc principalFromKeytab(path string) (string, error) {\n\tloadedKeytab, err := keytab.Load(path)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"load Kerberos keytab %s: %w\", path, err)\n\t}\n\tprincipals := map[string]struct{}{}\n\tfor _, entry := range loadedKeytab.Entries {\n\t\tprincipals[entry.Principal.String()] = struct{}{}\n\t}\n\tif len(principals) != 1 {\n\t\treturn \"\", fmt.Errorf(\"Kerberos keytab %s contains %d principals; configure kerberosprincipal explicitly\", path, len(principals))\n\t}\n\tfor principal := range principals {\n\t\treturn principal, nil\n\t}\n\treturn \"\", fmt.Errorf(\"Kerberos keytab %s contains no principals\", path)\n}\n\nfunc defaultKerberosConfigPath() string {\n\tif runtime.GOOS == \"windows\" {\n\t\tif windowsDirectory := os.Getenv(\"WINDIR\"); windowsDirectory != \"\" {\n\t\t\treturn filepath.Join(windowsDirectory, \"krb5.ini\")\n\t\t}\n\t}\n\treturn \"/etc/krb5.conf\"\n}\n\nfunc defaultKerberosCCachePath() string {\n\tif value := os.Getenv(\"KRB5CCNAME\"); value != \"\" {","sourceCodeStart":559,"sourceCodeEnd":595,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/cassandra-go/kerberos.go#L559-L595","documentation":"principalFromKeytab extracts a Kerberos principal from a keytab file by collecting the distinct principals across all keytab entries. It refuses to guess when the keytab contains more than one distinct principal, because picking the wrong one would authenticate as the wrong identity. The error tells you to set kerberosprincipal explicitly so the driver knows which principal to use.","triggerScenarios":"Calling selectKeytabCredential (via finalize) when kerberosprincipal is unset and the keytab at the configured path loads successfully but its Entries map to 2+ distinct entry.Principal.String() values.","commonSituations":"Reusing a host keytab (e.g. /etc/krb5.keytab) that holds entries for host/FQDN, HTTP/FQDN and user service principals; merging multiple service keytabs into one file; shared keytabs used by several services on one host.","solutions":["Set the kerberosprincipal option explicitly to the exact principal string that appears in the keytab.","Use klist -k <path> to list the principals in the keytab and pick the correct one.","If no principal is needed from this keytab, point the keytab configuration at a keytab containing only the intended principal."],"exampleFix":"// before\nkerberos: keytab=/etc/krb5.keytab (no principal set; keytab has 3 principals)\n// after\nkerberos: keytab=/etc/krb5.keytab, kerberosprincipal=svc-cassandra@EXAMPLE.COM","handlingStrategy":"validation","validationCode":"out, err := exec.Command(\"klist\", \"-k\", keytabPath).Output()\nif err != nil { return err }\nprincipals := map[string]struct{}{}\nfor _, line := range strings.Split(string(out), \"\\n\") {\n    if f := strings.Fields(line); len(f) >= 4 { principals[f[3]] = struct{}{} }\n}\nif len(principals) != 1 {\n    return fmt.Errorf(\"keytab has %d principals; set kerberosprincipal\", len(principals))\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"configure kerberosprincipal explicitly\") {\n    // surface config guidance to the operator instead of retrying\n}","preventionTips":["Always set kerberosprincipal in production configs even if the keytab currently has one principal.","Dedicate one keytab file per principal/service.","Run klist -k as part of deployment validation."],"tags":["kerberos","configuration","authentication"],"backgroundTag":"kerberos-keytab-ambiguous-principal","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}