router-for-me/CLIProxyAPI · warning

home kv store unavailable: %w

Error message

home kv store unavailable: %w

What it means

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.

Source

Thrown at internal/home/kv_helpers.go:26

	"fmt"
	"strings"
	"time"

	log "github.com/sirupsen/logrus"
)

func HashKeyPart(value string) string {
	sum := sha256.Sum256([]byte(value))
	return hex.EncodeToString(sum[:])
}

func CurrentKVClient() (*Client, bool, error) {
	client := Current()
	if client == nil {
		return nil, false, nil
	}
	if !client.Enabled() {
		return nil, true, fmt.Errorf("home kv store unavailable: %w", ErrDisabled)
	}
	if !client.HeartbeatOK() {
		return nil, true, fmt.Errorf("home kv store unavailable: %w", ErrNotConnected)
	}
	return client, true, nil
}

func KVGetJSONRequired(ctx context.Context, key string, out any) (bool, bool, error) {
	client, homeMode, errClient := CurrentKVClient()
	if !homeMode || errClient != nil {
		return homeMode, false, errClient
	}
	raw, found, errGet := client.KVGet(ctx, key)
	if errGet != nil || !found {
		return true, false, errGet
	}
	if errUnmarshal := json.Unmarshal(raw, out); errUnmarshal != nil {
		return true, false, errUnmarshal

View on GitHub (pinned to 78f0c4079e)

Solutions

1. Enable the home client in config if KV features are needed
2. If home is intentionally disabled, disable/avoid the KV-dependent feature as well
3. Handle this sentinel (errors.Is with ErrDisabled) to skip KV work cleanly instead of erroring

Example fix

// before
_, found, err := home.KVGetJSONRequired(ctx, key, &v)

// after
if _, _, err := home.KVGetJSONRequired(ctx, key, &v); err != nil && errors.Is(err, home.ErrDisabled) {
    log.Warn("home kv disabled; skipping shared state")
    return fallbackLocal()
}

if client := home.Current(); client == nil || !client.Enabled() {
    // home mode off or disabled: use local store, skip KV paths
    return loadLocalState()
}

if _, _, err := home.KVGetJSONRequired(ctx, key, &v); err != nil {
    if errors.Is(err, home.ErrDisabled) {
        return loadLocalState() // graceful degradation
    }
    return err
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• home ca fingerprint is required
• certificate id is required
• home certificate request returned unsupported resp prefix %q
• home: invalid address (host=%q port=%d)
• home tls: client certificate and key must be set together

AI-assisted analysis of router-for-me/CLIProxyAPI@78f0c4079e (2026-08-15). Data as JSON: /api/errors/ec43a011797ef101. Report an issue: GitHub.