Known Limitations
This page lists behaviors in the v1.0.0 source that affect read fallback and recovery. Each one has been reproduced and comes with a workaround.
Read and Recovery
| Behavior | Impact | Workaround |
|---|---|---|
When {DBPath}/{DB} is missing at startup, recovery returns early while walking the directory (sync.go:64-66) |
isHealth is never set to true and no health check runs; the instance stays in local mode for good and never touches Redis, while the log still prints Starting normal mode |
Call os.MkdirAll(filepath.Join(DBPath, strconv.Itoa(DB)), 0755) before New |
Set writes Data itself to Redis, but Get expects a Cache JSON value (set.go:36-44, get.go:47-51) |
Every memory miss (another instance, after a restart) fails to parse and switches to fallback once retries are exhausted | Read and write each key from the same long-lived instance, or make sure the key is in memory before reading |
redis.Nil (key missing) counts as a failure (get.go:41-50) |
Reading one missing key switches the instance to fallback until the next successful health check | Lower TimeToCheck to shorten the time spent in fallback |
Recovery deletes local files whether or not the pipeline succeeded (sync.go:84-87) |
Data that failed to resync survives only in memory and is lost when the process exits | None; the source must check the Exec result |
ttl = 0 entries are not in the recovery batch (sync.go:115-118) |
They return to Redis only after being read once (Read-Repair) | Set a TTL on keys that must persist |
| Normal mode reads memory first without asking Redis | External changes or deletes in Redis are invisible to this instance until the memory entry expires | Use short TTLs for keys that need to stay consistent |
Writes and Lifecycle
| Behavior | Impact | Workaround |
|---|---|---|
A nil Config.Redis panics |
New panics when the ping succeeds |
Always pass &redisFallback.Redis{} |
A nil value in Set panics (set.go:19) |
reflect.TypeOf(nil).String() |
Check for nil before calling |
| TTLs under one second truncate to 0 | Equivalent to no expiry | Use a TTL of at least one second |
Close does not flush the write queue |
Fallback writes from the last TimeToWrite never reach disk |
Wait longer than TimeToWrite before Close |
Close does not stop the writer goroutine or the 30-second sweep ticker |
Repeatedly creating and closing instances accumulates goroutines | Create one instance per process |
| The memory cache has no size limit | Entries are removed only on expiry; ttl = 0 entries are never removed |
Set a TTL on every key |
Del during fallback is not replayed to Redis on recovery |
The deleted key stays in Redis until it expires | Del the key again after recovery |
EmailConfig never sends mail |
The setting has no effect | — |
Error Messages
Get returns only Not found and Failed to parse, so the error cannot distinguish "missing", "expired", and "Redis down and nothing local". To learn the current mode, read the log (see Getting Started).