{"record":{"id":"e0d98cfe4e36fb00","repo":"micro/go-micro","slug":"failed-to-list-keys-in-bucket","errorCode":null,"errorMessage":"Failed to list keys in bucket","messagePattern":"Failed to list keys in bucket","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"store/nats-js-kv/nats.go","lineNumber":316,"sourceCode":"\t\to(&opt)\n\t}\n\n\tif opt.Database == \"\" {\n\t\topt.Database = n.opts.Database\n\t}\n\n\tif opt.Table == \"\" {\n\t\topt.Table = n.opts.Table\n\t}\n\n\tstore, ok := n.buckets.Get(opt.Database)\n\tif !ok {\n\t\treturn nil, ErrBucketNotFound\n\t}\n\n\tkeys, err := n.microKeys(store, opt.Table, opt.Prefix, opt.Suffix)\n\tif err != nil {\n\t\treturn nil, errors.Wrap(err, \"Failed to list keys in bucket\")\n\t}\n\n\treturn enforceLimits(keys, opt.Limit, opt.Offset), nil\n}\n\n// Close the store.\nfunc (n *natsStore) Close() error {\n\tn.conn.Close()\n\treturn nil\n}\n\n// String returns the name of the implementation.\nfunc (n *natsStore) String() string {\n\treturn \"NATS JetStream KeyValueStore\"\n}\n\n// thread safe way to initialize the connection.\nfunc (n *natsStore) initConn() error {","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/micro/go-micro/blob/24529f140421a11a33b6999ab7944f2021cfd69c/store/nats-js-kv/nats.go#L298-L334","documentation":"Returned by List when enumerating the keys of the bucket via microKeys fails. getKeys internally calls bucket.Keys() and only nats.ErrKeyNotFound is swallowed; any other error (connection, no leader, permissions) is wrapped as this error.","triggerScenarios":"Calling store.List() on a cached bucket whose JetStream stream is unreachable: connection lost, stream has no leader, or the caller lacks permission to read the stream's subjects.","commonSituations":"NATS server restarted while the process held a stale bucket handle; cluster failover during List; bucket stream deleted server-side by another process while still present in the local cache.","solutions":["Check the wrapped error; if it indicates a connection problem, reinitialize the store (close and re-create) and retry List","Verify the stream for the bucket still exists ('nats stream info KV_<bucket>') and recreate it if it was deleted","Ensure the NATS account has read/consumer permissions on the bucket's subjects","Retry with backoff if the error is a transient no-leader/timeout condition"],"exampleFix":"// before\nkeys, err := st.List(store.ListDatabase(\"default\"))\nif err != nil { return err }\n// after\nkeys, err := st.List(store.ListDatabase(\"default\"))\nif err != nil {\n    // reconnect and retry once\n    _ = st.Init()\n    keys, err = st.List(store.ListDatabase(\"default\"))\n    if err != nil { return err }\n}","handlingStrategy":"retry","validationCode":"if err := st.Init(); err != nil {\n    return fmt.Errorf(\"store not usable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"keys, err := st.List(opts...)\nif err != nil {\n    if strings.Contains(err.Error(), \"Failed to list keys in bucket\") {\n        _ = st.Init()\n        keys, err = st.List(opts...)\n    }\n    if err != nil { return nil, err }\n}","preventionTips":["Refresh connections on NATS disconnect events instead of reusing stale handles","Grant the account read/consumer permissions on bucket subjects","Alert on JetStream streams without leaders (cluster health monitoring)","Use bounded retries with backoff around List calls"],"tags":["nats","jetstream","list","kv"],"backgroundTag":"kv-keys-list-failed","analyzedSha":"24529f140421a11a33b6999ab7944f2021cfd69c","analyzedAt":"2026-09-01T02:52:24.923Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}