What causes "Failed to create bucket (%s)" in micro/go-micro?

Validate the bucket name (no spaces or '*'/'>' characters; valid NATS subject tokens)

Failed to create bucket (%s)

Error message

Failed to create bucket (%s)

What it means

Returned by mustGetBucket when the bucket did not exist and js.CreateKeyValue(kv) fails. Creation requires JetStream to add a stream named KV_<bucket> with the configured TTL/storage/description, and any rejection is wrapped here.

Source

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

		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
	} else if err != nil {
		return nil, false, errors.Wrap(err, "Failed to get object from bucket")
	}

	var kv KeyValueEnvelope

View on GitHub (pinned to 24529f1404)

Solutions

Validate the bucket name (no spaces or '*'/'>' characters; valid NATS subject tokens)
Check the wrapped error: if it says the stream already exists but isn't a KV view, remove or rename the conflicting stream ('nats stream rm KV_<bucket>')
Raise the account JetStream limits (max_streams/max_bytes) or free existing streams
Ensure JetStream is enabled and the account has permissions to create streams

Example fix

// before
mustGetBucketByName("my bucket") // invalid name
// after
mustGetBucketByName("my-bucket")

Defensive patterns

Strategy: validation

Validate before calling

var validBucket = regexp.MustCompile(`^[a-zA-Z0-9_-]+$`)
if !validBucket.MatchString(bucketName) {
    return fmt.Errorf("invalid bucket name: %q", bucketName)
}

Try / catch

if err := st.Init(); err != nil {
    if strings.Contains(err.Error(), "Failed to create bucket") {
        return fmt.Errorf("cannot create bucket %s: %w", name, err)
    }
    return err
}

Prevention

Restrict bucket names to alphanumerics, '-', '_' (no spaces or '*'/'>' tokens)
Pre-create buckets with explicit KeyValueConfig during deployment instead of on first write
Monitor account JetStream limits (max streams, max bytes)
Ensure no plain (non-KV) stream already uses the KV_<bucket> name

When it happens

Trigger: During Init() or first Write to a database: bucket name invalid (invalid NATS subject token characters), a stream named KV_<bucket> already exists as a non-KV stream, JetStream storage limits exceeded, JetStream disabled, or the account lacks permissions to add streams.

Common situations: Creating a bucket with a name containing spaces or wildcards ('*'/'>' characters are rejected for KV buckets); server account limits (max streams, max bytes) reached; collision with a manually created plain stream of the same name; JetStream memory/file quota exhausted.

Related errors

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