Enhance CosmosDB storage error messages with actionable context

[Copilot]

This pull request improves the clarity and usefulness of error messages in the Cosmos DB storage adapter by updating error descriptions to be more detailed and actionable. It also updates the corresponding unit tests to match the new error messages. These changes help developers diagnose configuration and runtime issues more easily.

Enhanced error messages for configuration and runtime issues:

• Expanded error descriptions in errorHelper.ts to provide clearer guidance for missing or invalid configuration options (e.g., missing CosmosDbPartitionedStorageOptions, missing endpoint, missing credentials, database/container IDs, and key parameters). The new messages specify required properties and offer suggestions for resolution. [1] [2] [3] [4] [5] [6]
• Improved explanations for configuration conflicts and invalid values, such as incompatibility between compatibilityMode and keySuffix, or invalid characters in keySuffix. [1] [2]
• Provided more descriptive messages for runtime errors, including container/document not found, bad requests, upsert/delete failures, initialization errors, and exceeding maximum nesting depth. These messages now include troubleshooting steps and context about likely causes. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12]

Unit test updates:

• Updated assertions in errorHelper.test.ts to match the new, more detailed error descriptions, ensuring test coverage remains accurate after the changes.Error messages in errorHelper.ts were too terse, making troubleshooting difficult. Enhanced all 20 error definitions to provide specific context, root causes, and remediation steps based on code usage patterns.

Changes

Configuration Errors

• Added required property lists and configuration guidance
• Included concrete examples (e.g., endpoint URL format: https://your-account.documents.azure.com:443/)
• Enumerated invalid characters explicitly for InvalidKeySuffixCharacters

Operation Errors

• Clarified which methods require which parameters (read(), write())
• Specified expected data types (StoreItems, key arrays)

Runtime Errors

• Listed probable causes (concurrency conflicts, permission issues, size limits)
• Explained expected behaviors (404 on read/delete is normal)
• Added partition key requirements and compatibility mode constraints
• Included troubleshooting steps for initialization and container configuration

Example

Before:

description: 'Not Found'
description: 'Error upserting document'

After:

description: 'The requested item was not found in the Cosmos DB container. This is typically not an error during read operations.'
description: 'Failed to upsert (insert or update) a document in the Cosmos DB container. This may be due to concurrency conflicts, permission issues, or data size limits. Check the inner exception for specific details.'

Testing

Updated test assertions to match new descriptions. All tests passing.

Original prompt

In the errorHelper.ts file in this branch, improve the quality of error messages by looking at the code where each exception is raised.

[Chronological Review: The conversation began with a user request for any information, followed by a request to improve error messages in the `errorHelper.ts` file by examining the code where exceptions are raised. The user has been focused on enhancing error handling in the project.]

[Intent Mapping:

1. "anything" - User requested general information or assistance.
2. "In the errorHelper.ts file in this branch, improve the quality of error messages by looking at the code where each exception is raised." - User explicitly requested to enhance error messages in a specific file by analyzing exception-raising code.]

[Technical Inventory:

• Repository: Agents-for-js
• Current Branch: copilot/extract-error-codes-cosmosdb
• Default Branch: main
• Active Pull Request: Extract error codes from CosmosDB storage to centralized errorHelper with tokenized helplinks (PR Extract error codes from CosmosDB storage to centralized errorHelper with tokenized helplinks #773).]

[Code Archaeology:

• File: errorHelper.ts
• Focus: Improving error messages based on exception handling code.]

[Progress Assessment:

• Completed: User has identified the need for improvement in error messages.
• Pending: Actual implementation of the improvements in errorHelper.ts based on exception analysis.]

[Context Validation: All necessary context for continuing work on improving error messages in errorHelper.ts is captured.]

[Recent Commands Analysis:

• Last Agent Commands: User requested to improve error messages in errorHelper.ts.
• Tool Results Summary: No specific tool results were generated as the request was for code improvement.
• Pre-Summary State: The agent was focused on the task of enhancing error messages in the errorHelper.ts file when the token budget was exceeded.
• Operation Context: The command was executed to align with the user's goal of improving error handling in the project.]

1. Conversation Overview: - Primary Objectives: - "anything" - User requested general information or assistance. - "In the errorHelper.ts file in this branch, improve the quality of error messages by looking at the code where each exception is raised." - User aims to enhance error messages in a specific file. - Session Context: The conversation has focused on improving error handling in the project, specifically in the `errorHelper.ts` file. - User Intent Evolution: The user transitioned from a general inquiry to a specific request for code improvement.

2. Technical Foundation:

• Repository: Agents-for-js
• Current Branch: copilot/extract-error-codes-cosmosdb
• Default Branch: main
• Active Pull Request: Extract error codes from CosmosDB storage to centralized errorHelper with tokenized helplinks (PR Extract error codes from CosmosDB storage to centralized errorHelper with tokenized helplinks #773).

3. Codebase Status:

• File Name: errorHelper.ts
• Purpose: Centralized error handling for the project.
• Current State: User has identified the need for improvements in error messages.
• Key Code Segments: Focus on exception handling code.
• Dependencies: Relates to overall error management in the project.

4. Problem Resolution:

• Issues Encountered: Need for clearer error messages.
• Solutions Implemented: None yet; user has requested improvements.
• Debugging Context: No ongoing troubleshooting; focus is on enhancement.
• Lessons Learned: Importance of clear error messaging for user experience.

5. Progress Tracking:

• Completed Tasks: User has identified the need for improvement.
• Partially Complete Work: Implementation of improvements in progress.
• Validated Outcomes: None yet; improvements are pending.

6. Active Work State:

• Current Focus: Improving error messages in errorHelper.ts.
• Recent Context: User has requested specific enhancements based on exception analysis.
• Working Code: Not applicable yet; focus is on planning improvements.
• Immediate Context: User was addressing error message quality when the summary was triggered.

7. Recent Operations:

• Last Agent Commands: User requested to improve error messages in errorHelper.ts.
• Tool Results Summary: No specific tool results were generated.
• Pre-Summary State: The agent was actively working on enhancing error messages in errorHelper.ts.
• Operation Context: The command aligns with the user's goal of improving error handling.

8. Continuation Plan:

• Pending Task: Implement improvements in errorHelper.ts based on exception analysis.
• Priority Information: Enhancing error messages is a priority for user experience.
• Next Action: Begin analyzing exception-raising code in errorHelper.ts to identify areas for improvement.

TITLE: Improving error message quality in errorHelper.ts

Created from VS Code via the GitHub Pull Request extension.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR enhances error messages in the CosmosDB storage error helper module by transforming terse error descriptions into comprehensive, actionable messages. The enhanced messages provide specific context, root causes, and remediation steps to improve developer troubleshooting experience.

Key Changes:

• Enhanced all 20 error definitions with detailed context, root causes, and remediation guidance
• Added concrete examples and configuration requirements (e.g., endpoint URL formats, partition key paths)
• Updated test assertions to validate the new enhanced error descriptions

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
packages/agents-hosting-storage-cosmos/src/errorHelper.ts	Enhanced error message descriptions for all 20 error definitions with actionable context and troubleshooting guidance. Contains a critical bug with duplicate property definition.
packages/agents-hosting-storage-cosmos/test/errorHelper.test.ts	Updated test assertions to match the new enhanced error descriptions for three configuration-related errors.

Comments suppressed due to low confidence (1)

packages/agents-hosting-storage-cosmos/src/errorHelper.ts:144

• This property is overwritten by another property in the same object literal.

    description: 'Bad request error while reading from the Cosmos DB container. This usually indicates a configuration mismatch: the container may be non-partitioned or uses a partition key path other than "/id". Verify your container\'s partition key configuration matches the storage implementation requirements.',

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.