{"record":{"id":"cb5350aa562a4b6e","repo":"juicedata/juicefs","slug":"unusable-ccache-s","errorCode":null,"errorMessage":"unusable ccache: %s","messagePattern":"unusable ccache: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/object/hdfs_kerberos.go","lineNumber":80,"sourceCode":"\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()\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\tccachePath = fmt.Sprintf(\"/tmp/krb5cc_%s\", u.Uid)\n\t}\n\n\tccache, err := credentials.LoadCCache(ccachePath)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tclient, err := krb.NewFromCCache(ccache, cfg, krbSettings...)\n\tif err != nil {\n\t\treturn nil, err","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/object/hdfs_kerberos.go#L62-L98","documentation":"Without a keytab, getKerberosClient uses the credential cache from KRB5CCNAME. The library only understands a bare file path or an explicit \"FILE:/path\" scheme; any other scheme (e.g. KCM:, DIR:, KEYRING:persistent) — or an unusable value while a ccache is required — returns \"unusable ccache: %s\". The krb5 library in use here only supports FILE-based caches.","triggerScenarios":"getKerberosClient called with KRB5CCNAME set to a non-FILE scheme such as \"KCM:1000\", \"DIR::/tmp/krb5cc_...\", or \"KEYRING:persistent:1000\"; the value contains \":\" but does not start with \"FILE:\".","commonSituations":"Modern Linux desktops / SSSD defaulting KRB5CCNAME to KCM or KEYRING; container runtimes inheriting DIR-style caches; MIT krb5 1.11+ default ccaches differing from the JuiceFS expectation.","solutions":["Re-kinit into a FILE cache and point KRB5CCNAME at it: kinit -c FILE:/tmp/krb5cc_juicefs principal && export KRB5CCNAME=FILE:/tmp/krb5cc_juicefs.","Convert the existing cache: kcm/DIR caches can be exported via kinit -R or by re-authenticating with KRB5CCNAME=FILE:... set.","If the cache is not needed, unset KRB5CCNAME so the library falls back to user.Current()'s home default path.","Prefer the keytab route (KRB5KEYTAB + KRB5PRINCIPAL) which bypasses the ccache entirely."],"exampleFix":"// before\nexport KRB5CCNAME=KCM:1000\n// after\nkinit -c FILE:/tmp/krb5cc_juicefs juicefs/host.example.com@EXAMPLE.COM\nexport KRB5CCNAME=FILE:/tmp/krb5cc_juicefs","handlingStrategy":"validation","validationCode":"cc := os.Getenv(\"KRB5CCNAME\")\nif strings.Contains(cc, \":\") && !strings.HasPrefix(cc, \"FILE:\") {\n    return fmt.Errorf(\"unsupported ccache type %q; only FILE caches are supported\", cc)\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"unusable ccache\") {\n    logger.Fatalf(\"Unsupported KRB5CCNAME: %v — re-kinit into a FILE cache\", err)\n}","preventionTips":["Use FILE-based credential caches; avoid KCM/DIR/KEYRING defaults on the host.","Export KRB5CCNAME=FILE:/path explicitly in service units.","Prefer keytab-based auth (KRB5KEYTAB+KRB5PRINCIPAL) for daemons.","Verify ccache type with klist -c before deployment."],"tags":["hdfs","kerberos","ccache","environment-variable"],"backgroundTag":"invalid-env-var-value","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"}