nats-io/nats-server · error

nil config on stream restore

Error message

nil config on stream restore

What it means

Stream restore bookkeeping received a nil StreamConfig where a concrete configuration is required, so the operation aborts instead of dereferencing nil. It signals a caller bug or an incomplete/corrupted restore request, not bad user data.

Source

Thrown at server/stream.go:9305

	if mset.closed.Load() {
		return nil, errStreamClosed
	}
	store := mset.store
	// V2 snapshots intentionally do not run the v1 checkMsgs pre-scan. Unlike
	// v1's raw file copy, v2 reads each message through LoadNextMsg, which uses
	// cacheLookup/msgFromBufEx and verifies the per-record checksum when a
	// freshly loaded cache entry is first read. Corrupt records therefore make
	// LoadNextMsg fail and abort the snapshot instead of silently entering the
	// backup.
	return mset.js.CreateStreamSnapshotV2(store, deadline, includeConsumers, mset.streamAssignment())
}

const snapsDir = "__snapshots__"

// RestoreStream will restore a stream from a snapshot.
func (a *Account) RestoreStream(ncfg *StreamConfig, r io.Reader) (*stream, error) {
	if ncfg == nil {
		return nil, errors.New("nil config on stream restore")
	}

	s, jsa, err := a.checkForJetStream()
	if err != nil {
		return nil, err
	}
	js := jsa.js
	if js == nil {
		return nil, NewJSNotEnabledForAccountError()
	}

	cfg, apiErr := s.checkStreamCfg(ncfg, a, false)
	if apiErr != nil {
		return nil, apiErr
	}

	sd := filepath.Join(jsa.storeDir, snapsDir)
	if _, err := os.Stat(sd); os.IsNotExist(err) {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Pass a fully populated StreamConfig in the restore request
2. Re-generate the restore backup if its metadata is incomplete
3. Report as a bug if it occurs while restoring a server-produced snapshot

When it happens

Trigger: Thrown at server/stream.go:9305 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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