Enhance CosmosDB storage error messages with actionable context

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

@@ -24,7 +24,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingCosmosDbStorageOptions: {
     code: -100000,
-    description: 'CosmosDbPartitionedStorageOptions is required.',
+    description: 'CosmosDbPartitionedStorageOptions is required. Provide a valid configuration object with cosmosClientOptions, databaseId, and containerId properties when initializing CosmosDbPartitionedStorage.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -33,7 +33,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingCosmosEndpoint: {
     code: -100001,
-    description: 'endpoint in cosmosClientOptions is required.',
+    description: 'The endpoint property in cosmosClientOptions is required. Provide your Cosmos DB account endpoint URL (e.g., https://your-account.documents.azure.com:443/).',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -42,7 +42,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingCosmosCredentials: {
     code: -100002,
-    description: 'key or tokenProvider in cosmosClientOptions is required.',
+    description: 'Authentication credentials are required in cosmosClientOptions. Provide either a key (connection key) or tokenProvider (for token-based authentication).',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -51,7 +51,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingDatabaseId: {
     code: -100003,
-    description: 'databaseId for CosmosDB is required.',
+    description: 'The databaseId property is required in CosmosDbPartitionedStorageOptions. Specify the name of the Cosmos DB database to use for storage.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -60,7 +60,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingContainerId: {
     code: -100004,
-    description: 'containerId for CosmosDB is required.',
+    description: 'The containerId property is required in CosmosDbPartitionedStorageOptions. Specify the name of the Cosmos DB container to use for storage.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -69,7 +69,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   InvalidCompatibilityModeWithKeySuffix: {
     code: -100005,
-    description: 'compatibilityMode cannot be true while using a keySuffix.',
+    description: 'Configuration conflict: compatibilityMode cannot be enabled (true) when using a keySuffix. Either disable compatibilityMode or remove the keySuffix from your configuration.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -78,7 +78,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   InvalidKeySuffixCharacters: {
     code: -100006,
-    description: 'Cannot use invalid Row Key characters: {keySuffix} in keySuffix',
+    description: 'The keySuffix "{keySuffix}" contains invalid characters. Keys cannot contain: \\, ?, /, #, tab, newline, carriage return, or *. Please remove these characters from your keySuffix configuration.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -87,7 +87,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingReadKeys: {
     code: -100007,
-    description: 'Keys are required when reading.',
+    description: 'The keys parameter is required when calling read(). Provide an array of storage keys to read.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -96,7 +96,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingWriteChanges: {
     code: -100008,
-    description: 'Changes are required when writing.',
+    description: 'The changes parameter is required when calling write(). Provide a StoreItems object containing the data to write.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -105,7 +105,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   UnsupportedCustomPartitionKeyPath: {
     code: -100009,
-    description: 'Custom Partition Key Paths are not supported. {containerId} has a custom Partition Key Path of {partitionKeyPath}.',
+    description: 'The container "{containerId}" uses a custom partition key path "{partitionKeyPath}", which is not supported. This storage implementation requires containers to use either "/id" as the partition key path or no partition key (for compatibility mode). Create a new container with the correct partition key configuration.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -114,7 +114,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   ContainerNotFound: {
     code: -100010,
-    description: 'Container {containerId} not found.',
+    description: 'The Cosmos DB container "{containerId}" was not found and could not be created. Verify the container exists or ensure the client has permissions to create it. If using compatibilityMode, the container must already exist.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -123,7 +123,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MissingKeyParameter: {
     code: -100011,
-    description: "The 'key' parameter is required.",
+    description: 'The key parameter is required and cannot be null or empty. Provide a valid storage key string.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -132,7 +132,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   ContainerReadNotFound: {
     code: -100012,
-    description: 'Not Found',
+    description: 'The requested item was not found in the Cosmos DB container. This is typically not an error during read operations.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -141,7 +141,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   ContainerReadBadRequest: {
     code: -100013,
-    description: 'Error reading from container. You might be attempting to read from a non-partitioned container or a container that does not use \'/id\' as the partitionKeyPath',
+    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.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -150,7 +150,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   ContainerReadError: {
     code: -100014,
-    description: 'Error reading from container',
+    description: 'An unexpected error occurred while reading from the Cosmos DB container. Check the inner exception for details about the specific error.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -159,7 +159,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   DocumentUpsertError: {
     code: -100015,
-    description: 'Error upserting document',
+    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.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -168,7 +168,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   DocumentDeleteNotFound: {
     code: -100016,
-    description: 'Not Found',
+    description: 'The document to delete was not found in the Cosmos DB container. This is typically not an error during delete operations.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -177,7 +177,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   DocumentDeleteError: {
     code: -100017,
-    description: 'Unable to delete document',
+    description: 'Failed to delete a document from the Cosmos DB container. This may be due to permission issues or network problems. Check the inner exception for specific details.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -186,7 +186,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   InitializationError: {
     code: -100018,
-    description: 'Failed to initialize Cosmos DB database/container: {databaseId}/{containerId}',
+    description: 'Failed to initialize the Cosmos DB database "{databaseId}" and container "{containerId}". Verify your connection credentials, ensure the account exists, and check that the client has appropriate permissions. See the inner exception for specific error details.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   },
 
@@ -195,7 +195,7 @@ export const Errors: { [key: string]: AgentErrorDefinition } = {
    */
   MaxNestingDepthExceeded: {
     code: -100019,
-    description: 'Maximum nesting depth of {maxDepth} exceeded. {additionalMessage}',
+    description: 'The data structure exceeds the maximum nesting depth of {maxDepth} levels. {additionalMessage} This limit is imposed to prevent stack overflow errors when storing deeply nested objects in Cosmos DB.',
     helplink: 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}'
   }
 }

packages/agents-hosting-storage-cosmos/test/errorHelper.test.ts

@@ -8,23 +8,23 @@ describe('Errors tests', () => {
     const error = Errors.MissingCosmosDbStorageOptions
 
     assert.strictEqual(error.code, -100000)
-    assert.strictEqual(error.description, 'CosmosDbPartitionedStorageOptions is required.')
+    assert.strictEqual(error.description, 'CosmosDbPartitionedStorageOptions is required. Provide a valid configuration object with cosmosClientOptions, databaseId, and containerId properties when initializing CosmosDbPartitionedStorage.')
     assert.strictEqual(error.helplink, 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}')
   })
 
   it('should have MissingCosmosEndpoint error definition', () => {
     const error = Errors.MissingCosmosEndpoint
 
     assert.strictEqual(error.code, -100001)
-    assert.strictEqual(error.description, 'endpoint in cosmosClientOptions is required.')
+    assert.strictEqual(error.description, 'The endpoint property in cosmosClientOptions is required. Provide your Cosmos DB account endpoint URL (e.g., https://your-account.documents.azure.com:443/).')
     assert.strictEqual(error.helplink, 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}')
   })
 
   it('should have MissingCosmosCredentials error definition', () => {
     const error = Errors.MissingCosmosCredentials
 
     assert.strictEqual(error.code, -100002)
-    assert.strictEqual(error.description, 'key or tokenProvider in cosmosClientOptions is required.')
+    assert.strictEqual(error.description, 'Authentication credentials are required in cosmosClientOptions. Provide either a key (connection key) or tokenProvider (for token-based authentication).')
     assert.strictEqual(error.helplink, 'https://aka.ms/M365AgentsErrorCodes/#{errorCode}')
   })