nats-io/nats-server · error

stream names do not match

Error message

stream names do not match

What it means

During restore, the stream name in the backed-up metadata file (JetStreamMetaFile) differs from the name in the config passed for the restore — the snapshot belongs to a different stream, so the restore is refused before the stream is created.

Source

Thrown at server/stream.go:9414

		if err != nil {
			return nil, err
		}
	}

	// Check metadata.
	// The cfg passed in will be the new identity for the stream.
	var fcfg FileStreamInfo
	b, err := os.ReadFile(filepath.Join(sdir, JetStreamMetaFile))
	if err != nil {
		return nil, err
	}
	if err := json.Unmarshal(b, &fcfg); err != nil {
		return nil, err
	}

	// Check to make sure names match.
	if fcfg.Name != cfg.Name {
		return nil, errors.New("stream names do not match")
	}

	// See if this stream already exists.
	if _, err := a.lookupStream(cfg.Name); err == nil {
		return nil, NewJSStreamNameExistRestoreFailedError()
	}
	// Move into the correct place here.
	ndir := filepath.Join(jsa.storeDir, streamsDir, cfg.Name)
	// Remove old one if for some reason it is still here.
	if _, err := os.Stat(ndir); err == nil {
		os.RemoveAll(ndir)
	}
	// Make sure our destination streams directory exists.
	if err := os.MkdirAll(filepath.Join(jsa.storeDir, streamsDir), defaultDirPerms); err != nil {
		return nil, err
	}
	// Move into new location.
	if err := os.Rename(sdir, ndir); err != nil {

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Restore using the same stream name as the backup
2. Align the metadata and config names if renaming intentionally
3. Verify the backup directory belongs to the intended stream

When it happens

Trigger: Thrown at server/stream.go:9414 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/9fe11d8b15df7004. Report an issue: GitHub.