micro/go-micro · error

Failed to store data in bucket '%s'

Error message

Failed to store data in bucket '%s'

What it means

Returned by Write when the NATS KV store rejects the Put of the marshaled envelope, wrapped with the key that failed. This means the JetStream bucket could not accept the write, most often due to a connection problem or a key name the bucket will not accept.

Source

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

		opt.Table = n.opts.Table
	}

	store, err := n.mustGetBucketByName(opt.Database)
	if err != nil {
		return err
	}

	b, err := json.Marshal(KeyValueEnvelope{
		Key:      rec.Key,
		Data:     rec.Value,
		Metadata: rec.Metadata,
	})
	if err != nil {
		return errors.Wrap(err, "Failed to marshal object")
	}

	if _, err := store.Put(n.NatsKey(opt.Table, rec.Key), b); err != nil {
		return errors.Wrapf(err, "Failed to store data in bucket '%s'", n.NatsKey(opt.Table, rec.Key))
	}

	return nil
}

// Delete removes the record with the corresponding key from the store.
func (n *natsStore) Delete(key string, opts ...store.DeleteOption) error {
	if err := n.initConn(); err != nil {
		return err
	}

	opt := store.DeleteOptions{}

	for _, o := range opts {
		o(&opt)
	}

	if opt.Database == "" {

View on GitHub (pinned to 24529f1404)

Solutions

1. Check the wrapped error for a NATS connection issue; if the server was restarted, recreate/reinit the store so a fresh connection is established
2. Validate/sanitize rec.Key and opt.Table to contain only valid NATS key characters (alphanumerics, '.', '-', '_', '/', no spaces, no trailing '.')
3. Verify the JetStream stream for the bucket is healthy ('nats stream info KV_<bucket>') and that the server has jetstream resources available
4. Retry the Write with backoff if the wrapped error is transient (nats: timeout / no responders)

Example fix

// before
key := fmt.Sprintf("user %s", email)
store.Write(&store.Record{Key: key, Value: data})
// after
key := strings.ReplaceAll(email, " ", "_")
store.Write(&store.Record{Key: key, Value: data})

var validKey = regexp.MustCompile(`^[a-zA-Z0-9._/-]+$`)
if !validKey.MatchString(rec.Key) {
    return fmt.Errorf("invalid key: %q", rec.Key)
}

if err := st.Write(rec); err != nil {
    if strings.Contains(err.Error(), "Failed to store data in bucket") {
        time.Sleep(backoff)
        err = st.Write(rec)
    }
    return err
}

When it happens

Trigger: Calling store.Write(rec) where the NATS connection is down/stale, the server has lost quorum for the stream, or the resulting key (n.NatsKey(opt.Table, rec.Key)) is empty or contains characters/sequences invalid for NATS subjects (e.g. spaces, trailing dots).

Common situations: NATS server restarted or network blip while the client keeps the old conn; writing a key derived from user input containing spaces or wildcard/invalid characters; bucket stream under low-memory/disk pressure causing publishes to fail; per-message TTL options incompatible with server version.

Related errors

• source not found: %s
• Failed to delete data
• Failed to list keys in bucket
• 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/764e412951d247b7. Report an issue: GitHub.