nats-io/nats-server · error

name required

Error message

name required

What it means

newFileStoreWithCreatedAndMode validates the StreamConfig before constructing a file-based message store and returns 'name required' when cfg.Name is the empty string. A file store cannot exist without a named stream, so the library fails fast during store creation (also used during recovery).

Source

Thrown at server/filestore.go:414

	// Checksum size for hash for msg records.
	recordHashSize = 8

	// Above this number of subjects, index.db may not be written regularly anymore, and
	// certain psim optimisations may not be used.
	highCardinalityThreshold = 1_000_000
)

func newFileStore(fcfg FileStoreConfig, cfg StreamConfig) (*fileStore, error) {
	return newFileStoreWithCreated(fcfg, cfg, time.Now().UTC(), nil, nil)
}

func newFileStoreWithCreated(fcfg FileStoreConfig, cfg StreamConfig, created time.Time, prf, oldprf keyGen) (fs *fileStore, err error) {
	return newFileStoreWithCreatedAndMode(fcfg, cfg, created, prf, oldprf, false)
}

func newFileStoreWithCreatedAndMode(fcfg FileStoreConfig, cfg StreamConfig, created time.Time, prf, oldprf keyGen, recovering bool) (fs *fileStore, err error) {
	if cfg.Name == _EMPTY_ {
		return nil, fmt.Errorf("name required")
	}
	if cfg.Storage != FileStorage {
		return nil, fmt.Errorf("fileStore requires file storage type in config")
	}
	// Default values.
	if fcfg.BlockSize == 0 {
		fcfg.BlockSize = dynBlkSize(cfg.Retention, cfg.MaxBytes, prf != nil)
	}
	if fcfg.BlockSize > maxBlockSize {
		return nil, fmt.Errorf("filestore max block size is %s", friendlyBytes(maxBlockSize))
	}
	if fcfg.CacheExpire == 0 {
		fcfg.CacheExpire = defaultCacheBufferExpiration
	}
	if fcfg.SubjectStateExpire == 0 {
		fcfg.SubjectStateExpire = defaultFssExpiration
	}
	if fcfg.SyncInterval == 0 {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Set StreamConfig.Name to a non-empty stream name before adding the stream
2. Include the 'name' field in the JetStream AddStream API payload
3. Validate config structs (name non-empty, Storage == FileStorage) before calling the file store constructor

Example fix

// before
cfg := StreamConfig{Storage: FileStorage}
// after
cfg := StreamConfig{Name: "ORDERS", Storage: FileStorage}

func streamConfigValidForFileStore(cfg StreamConfig) error {
    if cfg.Name == "" {
        return errors.New("name required")
    }
    if cfg.Storage != FileStorage {
        return errors.New("fileStore requires file storage type in config")
    }
    return nil
}

func hasName(cfg StreamConfig) bool { return cfg.Name != "" }

fs, err := newFileStoreWithCreated(fcfg, cfg, created, prf, oldprf)
if err != nil {
    if err.Error() == "name required" {
        // fix StreamConfig.Name and retry
    }
    return err
}

When it happens

Trigger: Creating a file-backed stream via AddStream/JetStream API with StreamConfig{Name: ""}; calling newFileStoreWithCreated directly with a zero-value StreamConfig.

Common situations: Programmatic stream creation where the Name field was forgotten; JSON config payloads missing the 'name' key; templating that renders an empty stream name.

Related errors

• max_request_batch must be set if it's JetStream limits are s
• consumer name can not contain '.', '*', '>', '\', '/'
• consumer durable name can not contain '.', '*', '>', '\', '/
• invalid mapping destination: wildcard index out of range
• invalid mapping destination: not enough arguments passed to

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/04bc3bcab11c343e. Report an issue: GitHub.