Skip to content

fix: report per-index write errors and inserted count when insert-many partially fails - #1386

Open
innolope-dev wants to merge 1 commit into
mongodb-js:mainfrom
innolope-dev:insert-many-partial-failure-report
Open

fix: report per-index write errors and inserted count when insert-many partially fails#1386
innolope-dev wants to merge 1 commit into
mongodb-js:mainfrom
innolope-dev:insert-many-partial-failure-report

Conversation

@innolope-dev

@innolope-dev innolope-dev commented Jul 23, 2026

Copy link
Copy Markdown

Proposed changes

When insert-many hits a MongoBulkWriteError, the generic error handler flattens it to a single message. That loses the two things an agent needs to recover: how many documents actually made it in, and which indices failed. With the driver's default ordered inserts a failure is usually partial — everything before the first failing index was inserted, everything after it was silently skipped — so the LLM can neither tell the user what state the collection is in nor retry with only the missing documents (retrying the whole batch would duplicate the already-inserted ones).

This PR adds a handleError override to InsertManyTool that, for MongoBulkWriteError, reports:

  • how many of the requested documents failed and how many were inserted,
  • each failing index with its error code and (secret-redacted) server message, wrapped via formatUntrustedData since errmsg can contain document values,
  • the ordered-insert skip semantics, and guidance to retry with only the documents that were not inserted.

The per-index list is capped at 10 entries so a batch with many failures can't blow up the response. All other errors fall through to super.handleError unchanged.

Example response for a 3-document batch where index 1 collides with an existing _id:

Error running insert-many: 1 of 3 document(s) failed to insert into mydb.coll1. 1 document(s) were inserted. Because inserts are ordered, documents after the first failing index were not attempted. Fix or remove the failing document(s) and retry with only the documents that were not inserted.
<untrusted-user-data-...>
- index 1 (code 11000): E11000 duplicate key error collection: mydb.coll1 index: _id_ dup key: ...
</untrusted-user-data-...>

Notes:

  • Added an integration test covering the partial-failure case (asserts the reported counts, the per-index line, and that the documents before/after the failing index were/weren't inserted). The pre-existing duplicate-key test now flows through the new branch and still passes.
  • api-extractor/reports/tools.public.api.md regenerated via pnpm run update:api (the protected override shows up in the tools report).
  • Ran the insert-many suite locally against a real mongod: 14 passed / 3 skipped (the search-enabled suites need a container runtime not available locally).

Checklist

…y partially fails

A MongoBulkWriteError from insert-many was flattened to a single generic
message, losing which documents were inserted and which failed. With the
driver's default ordered inserts a failure is usually partial: everything
before the first failing index is inserted, everything after it is skipped
— but the caller could not tell.

InsertManyTool now overrides handleError for MongoBulkWriteError and
reports the inserted count, each failing index with its error code and
(redacted) message via formatUntrustedData, the ordered-skip semantics,
and how to retry with only the documents that were not inserted. The
per-index list is capped at 10 entries to bound the response size.
@innolope-dev
innolope-dev requested a review from a team as a code owner July 23, 2026 20:50
@innolope-dev
innolope-dev requested review from himanshusinghs and removed request for a team July 23, 2026 20:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant