micro/go-micro · error

Failed to list keys in bucket

Error message

Failed to list keys in bucket

What it means

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.

Source

Thrown at store/nats-js-kv/nats.go:316

		o(&opt)
	}

	if opt.Database == "" {
		opt.Database = n.opts.Database
	}

	if opt.Table == "" {
		opt.Table = n.opts.Table
	}

	store, ok := n.buckets.Get(opt.Database)
	if !ok {
		return nil, ErrBucketNotFound
	}

	keys, err := n.microKeys(store, opt.Table, opt.Prefix, opt.Suffix)
	if err != nil {
		return nil, errors.Wrap(err, "Failed to list keys in bucket")
	}

	return enforceLimits(keys, opt.Limit, opt.Offset), nil
}

// Close the store.
func (n *natsStore) Close() error {
	n.conn.Close()
	return nil
}

// String returns the name of the implementation.
func (n *natsStore) String() string {
	return "NATS JetStream KeyValueStore"
}

// thread safe way to initialize the connection.
func (n *natsStore) initConn() error {

View on GitHub (pinned to 24529f1404)

Solutions

1. Check the wrapped error; if it indicates a connection problem, reinitialize the store (close and re-create) and retry List
2. Verify the stream for the bucket still exists ('nats stream info KV_<bucket>') and recreate it if it was deleted
3. Ensure the NATS account has read/consumer permissions on the bucket's subjects
4. Retry with backoff if the error is a transient no-leader/timeout condition

Example fix

// before
keys, err := st.List(store.ListDatabase("default"))
if err != nil { return err }
// after
keys, err := st.List(store.ListDatabase("default"))
if err != nil {
    // reconnect and retry once
    _ = st.Init()
    keys, err = st.List(store.ListDatabase("default"))
    if err != nil { return err }
}

if err := st.Init(); err != nil {
    return fmt.Errorf("store not usable: %w", err)
}

keys, err := st.List(opts...)
if err != nil {
    if strings.Contains(err.Error(), "Failed to list keys in bucket") {
        _ = st.Init()
        keys, err = st.List(opts...)
    }
    if err != nil { return nil, err }
}

When it happens

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

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

Related errors

• source not found: %s
• Failed to store data in bucket '%s'
• Failed to delete data
• Failed to get object from bucket
• error connecting to nats cluster %v: %w

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/e0d98cfe4e36fb00. Report an issue: GitHub.