How to Fix MongoDB Error 13113 (MergeStageNoMatchingDocument)
You get mongodb error 13113 when an aggregation merge stage cannot find a matching target document. To fix this MergeStageNoMatchingDocument failure, update your merge logic or insert the missing target records first. Data pipelines often merge output records into a target collection. When the engine requires an existing record to match, missing records stop the job. This safeguard keeps bad data out of your main tables. You must check your source data and target records before running the job
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.
You get mongodb error 13113 when an aggregation merge stage cannot find a matching target document. To fix this MergeStageNoMatchingDocument failure, update your merge logic or insert the missing target records first.
Data pipelines often merge output records into a target collection. When the engine requires an existing record to match, missing records stop the job. This safeguard keeps bad data out of your main tables. You must check your source data and target records before running the job again.
What causes mongodb error 13113 in your database
In the database engine, error code 13113 maps to the official MergeStageNoMatchingDocument name. This error happens during an aggregation pipeline that writes results to a collection. The merge stage compares incoming results from the pipeline against documents in the target collection. It checks specific join fields to see if a record already exists.
Sometimes, the merge step is set to fail when no matching document exists. If the pipeline sends a new key value, the lookup finds nothing in the target collection. The engine stops the query right away and returns mongodb error 13113 to the client app. This behavior prevents unwanted inserts when your job should only update current records.
Data drift between collections is a common root cause for this failure. A background job might delete a target record while your aggregation pipeline is still running. A typo in your match field names can also cause every lookup to miss. In sharded clusters, missing shard keys in the match condition can also break the lookup path.
How to diagnose and fix MergeStageNoMatchingDocument
Start by checking the source pipeline output before it reaches the final merge stage. Run the query without the final write step using an account with the read role. In MongoDB, a role grants privileges to run actions down to a collection level. The built-in read role lets you run find and check collection stats without changing data.
Compare the pipeline output keys against the keys in your target collection. Look for null values, missing fields, or mismatched data types between the two sets. For example, an integer key will not match a string key with the same digits. Fix any type mismatches inside an earlier stage of your pipeline before merging.
MongoDB Authentication & Authorization + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Next, decide if your pipeline should insert new documents when no match is found. If new records are valid, change the merge stage behavior to insert unmatched documents. If new records are not valid, filter out unknown keys earlier in the pipeline. You can use a lookup stage to keep only records that exist in the target collection.
Preventing merge failures in production pipelines
Do not give every team member write access to fix broken aggregation jobs by hand. The readWrite role lets users insert, update, remove, and even drop a whole collection. Instead, keep human users on read-only roles when they inspect failed pipeline inputs. When checking live data, make sure data masking rewrites emails, phone numbers, and card numbers in results.
Test your aggregation pipelines against a staging copy before running them on live data. Check that all required indexes exist on the target collection match fields. Missing indexes can slow down the merge step and increase the chance of race conditions. Keep your pipeline logic simple so your team can spot missing keys right away.
Add command guardrails and field masking beside MongoDB
Collection roles and IP rules control who connects to MongoDB. Yet an active client or agent session can still run a pipeline that writes data or reads raw personal fields. In practice, hoop.dev sits inline in the wire protocol beside your database as a sidecar for your MongoDB. For every command an agent or human sends in production, hoop.dev decides to pass, mask, block, or escalate it for review.
Using hoop.dev MongoDB controls, guardrails refuse banned commands before they run or hold risky calls for approval, and data masking rewrites matched fields in returned documents in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and generates evidence for GDPR, HIPAA, and PCI DSS programs. View the project on GitHub.
Frequently asked questions
What does MergeStageNoMatchingDocument mean in MongoDB?
It means an aggregation merge stage could not find a matching record in the target collection. The engine throws error code 13113 when the stage is set to fail on unmatched records.
Does error 13113 roll back the entire aggregation pipeline?
No, MongoDB does not roll back writes that finished before the error happened. Any documents merged before the unmatched record will stay in the target collection unless you use transactions.
Which role do I need to run an aggregation with a merge stage?
You need a role with write actions on the target collection, such as the readWrite role. The read role only allows read actions like find and cannot write merge results.
Related guides
In this post