How to Fix MongoDB Error 398 (StreamTerminated)

Published
Length
3 min read

Luis Felipe Dias

All posts

A broken network stream between the client and the server triggers mongodb error 398. You fix it by reconnecting the client and fixing network timeouts along the path. In the official server catalog, this failure is named StreamTerminated. It belongs to the CloseConnectionError category. When this fault occurs, the database closes the active socket right away. Your app sees a dropped request and must open a fresh socket to continue. What causes mongodb error 398 in your cluster The StreamTer

Your coding agents run with your access.

Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.

A broken network stream between the client and the server triggers mongodb error 398. You fix it by reconnecting the client and fixing network timeouts along the path.

In the official server catalog, this failure is named StreamTerminated. It belongs to the CloseConnectionError category. When this fault occurs, the database closes the active socket right away. Your app sees a dropped request and must open a fresh socket to continue.

What causes mongodb error 398 in your cluster

The StreamTerminated error means a data stream stopped before the task finished. The database engine groups this fault under the CloseConnectionError category. This category tells the client driver that the network link is dead. The client cannot reuse that socket for future work.

Several common events can cut a stream short in a live system. A load balancer or firewall might drop an idle link during a slow read. A replica set primary might step down while a change stream is open. Container restarts or node drains also kill active sockets mid-flight. Client timeouts set too low will also force the driver to shut the stream.

When a stream dies, the server stops the running operation to free up memory. If the task was a read or a change stream, no data changes occur. If a write was in flight, the app will not get a reply. Your team must check whether the write finished before sending it again.

How to diagnose and fix StreamTerminated in production

Start by checking your app logs and server logs at the exact failure timestamp. Look for node stepdowns, pod restarts, or proxy timeouts along the network path. Match the client drop time against load balancer idle timeout rules. If a firewall kills quiet sockets, adjust the keepalive time on the client.

When you check the database directly, use the least access needed for the job. MongoDB grants access through role-based rules on specific databases and collections. You can grant access down to a single collection when checking a failure. Do not hand out broad write roles just to inspect a broken stream.

MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices

Continue reading? Get the full guide.

Free. No spam. Unsubscribe anytime.

For most checks, the built-in read role gives your team enough power. The read role allows actions like find, listCollections, listIndexes, dbStats, collStats, and changeStream. It applies to all non-system collections in that database without allowing data changes. It blocks insert, update, remove, and dropCollection actions so live data stays safe.

Only use the readWrite role if you must fix broken records after a crash. That role adds insert, update, remove, createCollection, createIndex, dropIndex, and dropCollection actions. Notice that self-hosted deployments and MongoDB Atlas have different built-in roles. Still, both build their roles from the same set of privilege actions.

How to prevent future stream drops in your app

After you find the root cause, harden your client app against stream drops. Make sure your database driver uses connection pooling and automatic retries for safe reads. When the driver sees a CloseConnectionError fault, it should discard the dead socket. It can then open a new stream to a healthy node.

If your app uses change streams, save the resume token after each event. When StreamTerminated hits, the app can open a new change stream using that token. This step prevents missed events during a network blip or primary stepdown. Also protect sensitive fields like emails, phone numbers, card numbers, or national IDs. Masking rewrites matched fields in results during live debugging sessions.

Check MongoDB commands and documents on the wire

MongoDB roles and SCRAM login decide who opens a session. They do not check single commands or redact sensitive fields inside returned documents. With hoop.dev, you run an open-source proxy, a sidecar for your MongoDB, inline in the MongoDB wire protocol. On every command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.

Before a command runs, hoop.dev guardrails check its effect and refuse banned drops or writes with MongoDB error code 13, or hold risky commands for approval. On the way back, hoop.dev data masking rewrites sensitive fields in returned documents in memory, and every verdict is logged. See the open-source code on GitHub.

Frequently asked questions

What does StreamTerminated mean in MongoDB?

StreamTerminated is the official name for error code 398 in MongoDB. It belongs to the CloseConnectionError group and means an active network stream ended early.

Is it safe to retry operations after error 398?

Reads and change streams are safe to retry right away on a new socket. For writes, check if the change applied before sending the write a second time.

Which MongoDB role should engineers use to debug stream errors?

Use the built-in read role on the target database during your investigation. It allows find, dbStats, collStats, and changeStream actions while blocking any data edits.

The query runs. The emails stay hidden.