Fix NATS Stream Mirror Not Found Errors (2026)

NATS Stream Mirror Not Found errors mean a consumer is trying to read from a stream that doesn’t exist, usually because the stream wasn’t properly configured or was deleted.

Common Causes and Fixes for "Stream Mirror Not Found"

1. Stream Name Mismatch (Most Common)

   • Diagnosis: Check your stream configuration (nats stream info <stream_name>) and compare it exactly with the stream name specified in your consumer’s configuration (often found in nats consumer list <stream_name> or in the consumer’s definition file/API call). Case sensitivity matters, and typos are frequent.
   • Fix: Update the consumer’s configuration to match the exact stream name. If the stream is my-stream, ensure the consumer is referencing my-stream and not My-Stream or my_stream.
   • Why it works: The NATS server uses the stream name as a direct lookup key. Any discrepancy prevents it from locating the stream.

2. Stream Was Deleted or Not Created

   • Diagnosis: Use nats stream list to see if the stream you expect to exist is actually present. If it’s not, it was likely never created or has been explicitly deleted.
   • Fix: Recreate the stream with the correct configuration. For example, using nats stream add my-stream --subjects "events.>" --retention workqueue --max-msgs 10000 --storage file.
   • Why it works: The stream needs to be actively registered with the NATS server to be available for consumers.

3. Mirror Stream Configuration Error

   • Diagnosis: If you are using a mirror, the stream definition itself might be pointing to a non-existent source stream or have other invalid mirror parameters. Check the stream info for the mirror stream: nats stream info <mirror_stream_name>. Look for the Mirror section in the output.
   • Fix: Correct the Source stream name within the mirror stream’s configuration, or ensure the source stream exists and is accessible. For example, if mirror-stream is supposed to mirror source-stream, and source-stream is misspelled or missing, correct it in the mirror-stream definition.
   • Why it works: The mirror stream definition is faulty, preventing NATS from establishing the connection to its source and thus making the mirror appear non-existent.

4. NATS Server Restart Without Persisted Stream State

   • Diagnosis: If your NATS server was restarted without proper persistence configuration, streams might not have been reloaded. Check the NATS server logs for messages indicating stream loading failures or missing stream definitions on startup.
   • Fix: Ensure your NATS server is configured for stream persistence and that the persistence directory is accessible and contains the stream definition files. For example, in nats-server.conf, ensure store_dir: "/path/to/nats/store" is set and the directory exists.
   • Why it works: Streams are stored on disk. If the server can’t find or load these definitions on startup, they won’t be available.

5. Incorrect Account/JetStream Context

   • Diagnosis: If you are using NATS accounts (multi-tenancy), ensure the user/application creating the stream and the user/application creating the consumer are operating within the same account, or that the consumer’s account has appropriate permissions to access the stream in another account. Use nats account list and nats stream list --account <account_name> to verify.
   • Fix: Configure your clients or NATS server to use the correct account context. This might involve setting NATS_ACCOUNT environment variables or specifying accounts in client connection configurations.
   • Why it works: Streams are scoped to accounts. A consumer in one account cannot see a stream in another unless explicitly permitted.

6. JetStream Not Enabled or Misconfigured on Server

   • Diagnosis: Verify that JetStream is enabled on your NATS server instance. Check the server’s configuration file (nats-server.conf) for jetstream: { enabled: true }. Also, check server logs for any JetStream initialization errors.
   • Fix: Ensure JetStream is enabled in the nats-server.conf and restart the NATS server. If you’re using a cluster, ensure all nodes have JetStream enabled and configured identically.
   • Why it works: The "Stream" concept is part of JetStream. If JetStream is disabled, no streams can be created or accessed.

7. Consumer Created Before Stream (Race Condition)

   • Diagnosis: In automated deployments or rapid startup sequences, a consumer might be configured and started before the corresponding stream is fully created and registered by the NATS server. Check deployment logs for the order of operations.
   • Fix: Implement a retry mechanism for consumer creation or add a delay in your deployment script to ensure the stream exists before attempting to create the consumer.
   • Why it works: The NATS server needs a brief moment to initialize and register a new stream. A consumer attempting to attach too early will fail.

After fixing these, you might encounter "Consumer Not Found" errors if the consumer itself was never properly created or if its name is incorrect.