microsoft / microsoft/vscode-documentdb

Improve error reporting for `insertDocuments`

Open
#135 0 comments 0 reactions 1 assignee View on GitHub

@xingfan-git is already working on this.

Since Jun 18, 2025.

enhancement
Dominant language
TypeScript
Stars
31
Forks
22
Avg merge
2d 20h
Merged PRs (30d)
21

Description

Improve error reporting for insertDocuments by including document details

Description

The insertDocuments method in ClustersClient.ts currently receives an array of WriteError objects when bulk insert operations fail. Each WriteError contains an index property that references the failed document's position in the original input array. However, the current error reporting only displays generic error messages without leveraging this index to provide more specific information about which documents failed.

Current Behavior

When documents fail to insert, the error handler logs:

  • General error message
  • Descriptive error message (if available)
Proposed Enhancement

Enhance error reporting to include specific document information by:

  1. Using the WriteError.index property to identify the failed document from the original array
  2. Extracting and displaying the document's _id field (if present) to help users identify which specific documents failed
  3. Optionally including other identifying fields or a preview of the document structure
Implementation Considerations
Error Reporting Safety
  • The enhanced error reporting must be wrapped in robust try-catch blocks to prevent any parsing or processing errors from interrupting the bulk import operation
  • Failed error reporting should gracefully fall back to the current generic messages
Performance Concerns

Several approaches could prevent performance degradation when processing large numbers of errors:

  1. Simple timeout per document: Set a maximum processing time (e.g., 50ms) for extracting information from each failed document
  2. Batch processing with timeout: Process error reporting in batches with an overall timeout
  3. Async processing with Promise.race: Use Promise.race with a timeout promise to ensure error processing doesn't block indefinitely
  4. Lazy evaluation: Only process document details when the error is actually displayed/accessed

While option 3 (array of promises with timeout) might seem like overkill for simple field extraction, it could be justified if we want to:

  • Extract multiple fields from documents
  • Handle complex nested structures
  • Provide formatted previews of document content
Example Enhanced Error Output
Write error: Document validation failed - The document with _id: "507f1f77bcf86cd799439011" failed validation due to missing required field 'name'

Note: This issue was generated with AI assistance based on detailed input and instructions from @tnaum-ms

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.