nats-io/nats-server · error

error restoring consumer [%q]: %v

Error message

error restoring consumer [%q]: %v

What it means

While restoring a JetStream account from a snapshot, reading a consumer's meta file path failed the os.Stat existence check — the expected consumer metadata file (JetStreamMetaFile) is missing in the extracted snapshot directory. The affected stream/consumer dir is named; the restore aborts and the temp dir is removed. Corrupt or incomplete snapshot.

Source

Thrown at server/stream.go:9461

		mset.setCreatedTime(fcfg.Created)
	}

	// Make sure we do an update if the configs have changed.
	if !reflect.DeepEqual(fcfg.StreamConfig, cfg) {
		if err := mset.update(&cfg); err != nil {
			return nil, err
		}
	}

	// Now do consumers.
	odir := filepath.Join(ndir, consumerDir)
	ofis, _ := os.ReadDir(odir)
	for _, ofi := range ofis {
		metafile := filepath.Join(odir, ofi.Name(), JetStreamMetaFile)
		metasum := filepath.Join(odir, ofi.Name(), JetStreamMetaFileSum)
		if _, err := os.Stat(metafile); os.IsNotExist(err) {
			mset.stop(true, false)
			return nil, fmt.Errorf("error restoring consumer [%q]: %v", ofi.Name(), err)
		}
		buf, err := os.ReadFile(metafile)
		if err != nil {
			mset.stop(true, false)
			return nil, fmt.Errorf("error restoring consumer [%q]: %v", ofi.Name(), err)
		}
		if _, err := os.Stat(metasum); os.IsNotExist(err) {
			mset.stop(true, false)
			return nil, fmt.Errorf("error restoring consumer [%q]: %v", ofi.Name(), err)
		}
		var cfg FileConsumerInfo
		if err := json.Unmarshal(buf, &cfg); err != nil {
			mset.stop(true, false)
			return nil, fmt.Errorf("error restoring consumer [%q]: %v", ofi.Name(), err)
		}
		isEphemeral := !isDurableConsumer(&cfg.ConsumerConfig)
		if isEphemeral {
			// This is an ephermal consumer and this could fail on restart until

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Re-create the snapshot ensuring consumers finish exporting
2. Check source server logs for consumer meta write failures
3. Match server versions between snapshot source and restore target

When it happens

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