or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

core-parsing.md envelopes.md errors.md helpers.md index.md middleware.md parser-decorator.md schemas.md

tile.json

Error Handling

ParseError

Custom error wrapping validation errors with context.

class ParseError extends Error {
  name: string;           // "ParseError"
  message: string;        // Error description
  cause?: unknown;        // Original error (e.g., ZodError)
}

Usage:

import { parse, ParseError } from '@aws-lambda-powertools/parser';
import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';

try {
  const event = parse(data, undefined, EventBridgeSchema);
} catch (error) {
  if (error instanceof ParseError) {
    console.error('Parsing failed:', error.message);
    console.error('Caused by:', error.cause);
  }
}

Error messages:

Schema: "Failed to parse schema. This error was caused by: <details>"
Envelope: "Failed to parse EventBridge envelope. This error was caused by: <details>"
Array: "Failed to parse SQS Record at index 2. This error was caused by: <details>"

Safe Parsing

Returns ParsedResult instead of throwing.

type ParsedResult<Input, Output> =
  | { success: true; data: Output }
  | { success: false; error: Error; originalEvent?: Input };

With parse()

const result = parse(event, EventBridgeEnvelope, orderSchema, true);

if (result.success) {
  console.log(result.data.orderId);
} else {
  console.error(result.error.message);
  console.error(result.originalEvent);
}

With @parser

import { parser } from '@aws-lambda-powertools/parser';
import { SqsEnvelope } from '@aws-lambda-powertools/parser/envelopes';
import type { ParsedResult } from '@aws-lambda-powertools/parser/types';

class Lambda {
  @parser({ schema: orderSchema, envelope: SqsEnvelope, safeParse: true })
  async handler(event: ParsedResult<unknown, Order[]>, _context: Context) {
    if (event.success) {
      event.data.forEach(order => console.log(order.id));
      return { statusCode: 200 };
    } else {
      console.error(event.error.message);
      return { statusCode: 400, body: 'Invalid event' };
    }
  }
}

With middleware

const lambdaHandler = async (event: ParsedResult<unknown, Order>) => {
  if (event.success) {
    console.log(event.data.orderId);
    return { statusCode: 200 };
  } else {
    return { statusCode: 400, body: JSON.stringify({ error: 'Invalid format' }) };
  }
};

export const handler = middy(lambdaHandler).use(
  parser({ schema: orderSchema, envelope: EventBridgeEnvelope, safeParse: true })
);

Custom Error Recovery

Extract validation details from ZodError:

import { parse, ParseError } from '@aws-lambda-powertools/parser';
import { ZodError } from 'zod';

const result = parse(event, SqsEnvelope, orderSchema, true);

if (!result.success) {
  if (result.error instanceof ParseError && result.error.cause instanceof ZodError) {
    const zodError = result.error.cause;

    zodError.issues.forEach(issue => {
      console.error(`${issue.path.join('.')}: ${issue.message}`);
    });

    await sendToDeadLetterQueue(result.originalEvent, zodError.issues);
  }
}

Partial Success Handling

Process records individually:

import { parse } from '@aws-lambda-powertools/parser';
import { SqsSchema } from '@aws-lambda-powertools/parser/schemas';
import { JSONStringified } from '@aws-lambda-powertools/parser/helpers';

const sqsEvent = parse(event, undefined, SqsSchema);

const results = { succeeded: [], failed: [] };

for (const record of sqsEvent.Records) {
  const result = JSONStringified(orderSchema).safeParse(record.body);

  if (result.success) {
    console.log('Processing:', result.data.id);
    results.succeeded.push(record.messageId);
  } else {
    console.error('Failed:', record.messageId, result.error.message);
    results.failed.push({ messageId: record.messageId, error: result.error.message });
  }
}

// Return failed IDs for SQS partial batch failure
if (results.failed.length > 0) {
  return {
    batchItemFailures: results.failed.map(f => ({ itemIdentifier: f.messageId }))
  };
}

Best Practices

Use safeParse: true for untrusted data
Log originalEvent for debugging
Check instanceof ParseError to distinguish errors
Access error.cause for detailed validation errors (ZodError)
Handle array results individually when partial failures expected
Return appropriate status codes in API handlers