AWS powertools documentation change

Service: powertools · 2026-07-13 · Documentation low

File: powertools/typescript/latest/features/parser.md

Summary

Added documentation for handling parse errors inline using errorHandler callback, including code examples for Middy and decorator patterns

Security assessment

The change adds error handling capabilities for parsing failures but doesn't address any specific security vulnerability. It improves error management by allowing custom responses instead of exceptions, which is a reliability enhancement rather than a security fix.

Diff

diff --git a/powertools/typescript/latest/features/parser.md b/powertools/typescript/latest/features/parser.md
index 833bb8073..f17c4a86c 100644
--- a//powertools/typescript/latest/features/parser.md
+++ b//powertools/typescript/latest/features/parser.md
@@ -64,0 +65 @@ Event Handler
+        * Handling parse errors inline 
@@ -72,0 +74 @@ Event Handler
+      * [ Data Masking  ](../data-masking/)
@@ -73,0 +76 @@ Event Handler
+      * [ Signer  ](../signer/)
@@ -107,0 +111 @@ Table of contents
+  * Handling parse errors inline 
@@ -1604,0 +1609,194 @@ Middy.js middlewareDecorator
+## Handling parse errors inline¶
+
+If you want to intercept a parsing failure and return a custom response instead of throwing, use the `errorHandler` option. The callback receives the `ParseError` and the original, unparsed event, and must return synchronously - `errorHandler` does not support `async` functions, and providing one is a type error.
+
+If `errorHandler` returns a value, it is used as the response and the error is not thrown. If it returns `undefined`, the original error is rethrown.
+
+`errorHandler` and `safeParse` are mutually exclusive: with `safeParse` the parser never throws, so `errorHandler` would never be invoked.
+
+Middy.js middlewareDecorator
+    
+    
+     1
+     2
+     3
+     4
+     5
+     6
+     7
+     8
+     9
+    10
+    11
+    12
+    13
+    14
+    15
+    16
+    17
+    18
+    19
+    20
+    21
+    22
+    23
+    24
+    25
+    26
+    27
+    28
+    29
+    30
+    31
+    32
+    33
+    34
+    35
+    36
+
+| 
+    
+    
+    import { Logger } from '@aws-lambda-powertools/logger';
+    import { parser } from '@aws-lambda-powertools/parser/middleware';
+    import middy from '@middy/core';
+    import { z } from 'zod';
+    
+    const logger = new Logger();
+    
+    const orderSchema = z.object({
+      id: z.number().positive(),
+      description: z.string(),
+      items: z.array(
+        z.object({
+          id: z.number().positive(),
+          quantity: z.number(),
+          description: z.string(),
+        })
+      ),
+      optionalField: z.string().optional(),
+    });
+    
+    export const handler = middy()
+      .use(
+        parser({
+          schema: orderSchema,
+          errorHandler: (error, event) => {
+            // (1)!
+            logger.error('Failed to parse event', { error, event }); // (2)!
+            return { statusCode: 400, body: 'Invalid order payload' }; // (3)!
+          },
+        })
+      )
+      .handler(async (event): Promise<void> => {
+        for (const item of event.items) {
+          logger.info('Processing item', { item });
+        }
+      });
+      
+  
+---|---  
+  
+  1. Use `errorHandler` to intercept a `ParseError` and return a custom response
+  2. Use `error` and `event` to log the failure and the original, unparsed event
+  3. Returning a value short-circuits the parse failure with that value
+
+
+    
+    
+     1
+     2
+     3
+     4
+     5
+     6
+     7
+     8
+     9
+    10
+    11
+    12
+    13
+    14
+    15
+    16
+    17
+    18
+    19
+    20
+    21
+    22
+    23
+    24
+    25
+    26
+    27
+    28
+    29
+    30
+    31
+    32
+    33
+    34
+    35
+    36
+    37
+    38
+    39
+    40
+    41
+
+| 
+    
+    
+    import type { LambdaInterface } from '@aws-lambda-powertools/commons/types';
+    import { Logger } from '@aws-lambda-powertools/logger';
+    import { parser } from '@aws-lambda-powertools/parser';
+    import type { Context } from 'aws-lambda';
+    import { z } from 'zod';
+    
+    const logger = new Logger();
+    
+    const orderSchema = z.object({
+      id: z.number().positive(),
+      description: z.string(),
+      items: z.array(
+        z.object({
+          id: z.number().positive(),
+          quantity: z.number(),
+          description: z.string(),
+        })
+      ),
+      optionalField: z.string().optional(),
+    });
+    
+    type Order = z.infer<typeof orderSchema>;
+    
+    class Lambda implements LambdaInterface {
+      @parser({
+        schema: orderSchema,
+        errorHandler: (error, event) => {
+          // (1)!
+          logger.error('Failed to parse event', { error, event }); // (2)!
+          return { statusCode: 400, body: 'Invalid order payload' }; // (3)!
+        },
+      })
+      public async handler(event: Order, _context: Context): Promise<void> {
+        for (const item of event.items) {
+          logger.info('Processing item', { item });
+        }
+      }
+    }
+    
+    const myFunction = new Lambda();
+    export const handler = myFunction.handler.bind(myFunction);
+      
+  
+---|---