{"record":{"id":"ec43a011797ef101","repo":"router-for-me/CLIProxyAPI","slug":"home-kv-store-unavailable-w","errorCode":null,"errorMessage":"home kv store unavailable: %w","messagePattern":"home kv store unavailable: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"internal/home/kv_helpers.go","lineNumber":26,"sourceCode":"\t\"fmt\"\n\t\"strings\"\n\t\"time\"\n\n\tlog \"github.com/sirupsen/logrus\"\n)\n\nfunc HashKeyPart(value string) string {\n\tsum := sha256.Sum256([]byte(value))\n\treturn hex.EncodeToString(sum[:])\n}\n\nfunc CurrentKVClient() (*Client, bool, error) {\n\tclient := Current()\n\tif client == nil {\n\t\treturn nil, false, nil\n\t}\n\tif !client.Enabled() {\n\t\treturn nil, true, fmt.Errorf(\"home kv store unavailable: %w\", ErrDisabled)\n\t}\n\tif !client.HeartbeatOK() {\n\t\treturn nil, true, fmt.Errorf(\"home kv store unavailable: %w\", ErrNotConnected)\n\t}\n\treturn client, true, nil\n}\n\nfunc KVGetJSONRequired(ctx context.Context, key string, out any) (bool, bool, error) {\n\tclient, homeMode, errClient := CurrentKVClient()\n\tif !homeMode || errClient != nil {\n\t\treturn homeMode, false, errClient\n\t}\n\traw, found, errGet := client.KVGet(ctx, key)\n\tif errGet != nil || !found {\n\t\treturn true, false, errGet\n\t}\n\tif errUnmarshal := json.Unmarshal(raw, out); errUnmarshal != nil {\n\t\treturn true, false, errUnmarshal","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/router-for-me/CLIProxyAPI/blob/78f0c4079e3e6273d65d03b5549cffc898703264/internal/home/kv_helpers.go#L8-L44","documentation":"Returned by CurrentKVClient in internal/home/kv_helpers.go when a KV operation is attempted in home mode but the home client is not enabled — it wraps the ErrDisabled sentinel with the 'home kv store unavailable' prefix. Home mode was detected (Current() returned a client) but Enabled() is false, so KV reads/writes cannot proceed.","triggerScenarios":"Calling KVGetJSONRequired / KV set helpers while the home feature is disabled in config or the client was constructed but not enabled (e.g. enabled: false, or disabled at runtime before close).","commonSituations":"Feature that uses the KV store is turned on while the home block is enabled: false; config hot-reload disabled home while KV-dependent modules still run; test invoking KV helpers without enabling home.","solutions":["Enable the home client in config if KV features are needed","If home is intentionally disabled, disable/avoid the KV-dependent feature as well","Handle this sentinel (errors.Is with ErrDisabled) to skip KV work cleanly instead of erroring"],"exampleFix":"// before\n_, found, err := home.KVGetJSONRequired(ctx, key, &v)\n\n// after\nif _, _, err := home.KVGetJSONRequired(ctx, key, &v); err != nil && errors.Is(err, home.ErrDisabled) {\n    log.Warn(\"home kv disabled; skipping shared state\")\n    return fallbackLocal()\n}","handlingStrategy":"fallback","validationCode":"if client := home.Current(); client == nil || !client.Enabled() {\n    // home mode off or disabled: use local store, skip KV paths\n    return loadLocalState()\n}","typeGuard":null,"tryCatchPattern":"if _, _, err := home.KVGetJSONRequired(ctx, key, &v); err != nil {\n    if errors.Is(err, home.ErrDisabled) {\n        return loadLocalState() // graceful degradation\n    }\n    return err\n}","preventionTips":["Check client.Enabled() before entering KV-dependent code paths","Keep feature flags for KV features aligned with the home enabled flag"],"tags":["go","kv-store","configuration","home"],"backgroundTag":null,"analyzedSha":"78f0c4079e3e6273d65d03b5549cffc898703264","analyzedAt":"2026-08-15T12:26:37.444Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}