micro/go-micro · error

Failed to get bucket (%s)

Error message

Failed to get bucket (%s)

What it means

Returned by mustGetBucket (used by Init and mustGetBucketByName) when js.KeyValue(bucket) fails with an error other than nats.ErrBucketNotFound. That lookup failure means JetStream could not be queried about the bucket at all, so the store cannot proceed to create it.

Source

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

func (n *natsStore) mustGetBucketByName(name string) (nats.KeyValue, error) {
	return n.mustGetBucket(&nats.KeyValueConfig{
		Bucket:      name,
		Description: n.description,
		TTL:         n.ttl,
		Storage:     n.storageType,
	})
}

// mustGetBucket creates a new bucket if it does not exist yet.
func (n *natsStore) mustGetBucket(kv *nats.KeyValueConfig) (nats.KeyValue, error) {
	if store, ok := n.buckets.Get(kv.Bucket); ok {
		return store, nil
	}

	store, err := n.js.KeyValue(kv.Bucket)
	if err != nil {
		if !errors.Is(err, nats.ErrBucketNotFound) {
			return nil, errors.Wrapf(err, "Failed to get bucket (%s)", kv.Bucket)
		}

		store, err = n.js.CreateKeyValue(kv)
		if err != nil {
			return nil, errors.Wrapf(err, "Failed to create bucket (%s)", kv.Bucket)
		}
	}

	n.buckets.Set(kv.Bucket, store)

	return store, nil
}

// getRecord returns the record with the given key from the nats kv store.
func (n *natsStore) getRecord(bucket nats.KeyValue, key string) (*store.Record, bool, error) {
	obj, err := bucket.Get(key)
	if errors.Is(err, nats.ErrKeyNotFound) {
		return nil, false, store.ErrNotFound

View on GitHub (pinned to 24529f1404)

Solutions

1. Verify JetStream is enabled on the server and the account can access streams ('nats stream ls')
2. Check network/credentials; reconnect and retry Init after fixing the connection
3. Increase JetStream API request timeout in the nats.JSOpt options if the wrapped error is a timeout
4. Check server logs for errors about the stream lookup at the time of the failure

Example fix

// before
ctx = context.WithValue(ctx, jsOptionsKey{}, []nats.JSOpt{nats.MaxWait(50 * time.Millisecond)})
// after
ctx = context.WithValue(ctx, jsOptionsKey{}, []nats.JSOpt{nats.MaxWait(5 * time.Second)})

nc, _ := nats.Connect(url)
js, err := nc.JetStream(nats.MaxWait(5 * time.Second))
if err != nil { return err }
if _, err := js.AccountInfo(); err != nil {
    return fmt.Errorf("jetstream unavailable: %w", err)
}

if err := st.Init(); err != nil {
    if strings.Contains(err.Error(), "Failed to get bucket") {
        return fmt.Errorf("cannot query jetstream; check server/JS health: %w", err)
    }
    return err
}

When it happens

Trigger: During Init() with preconfigured kvConfigs or on first Write: the JetStream request times out, the connection is broken, the server has JetStream disabled, or the account lacks permission to look up the stream.

Common situations: NATS server unreachable right after Connect succeeded (async disconnect); JetStream not enabled; wrong account/credentials limiting stream visibility; short JetStream request timeouts passed via JS options.

Related errors

• Failed to delete bucket
• Failed to create bucket (%s)
• source not found: %s
• error connecting to nats cluster %v: %w
• error while obtaining JetStream context: %w

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