AWS AppSync Lambda解析器响应映射模板无法显示自定义错误属性

I've run into exactly this issue before—when throwing custom errors with status codes from a Lambda resolver, AppSync wasn't picking up the custom properties and instead returned that generic Lambda:Unhandled error. Here's how I fixed it step by step:

1. Check Where Your Custom Error Lives in the AppSync Context #

When an uncaught error is thrown from Lambda, AppSync wraps it in the $ctx.error.cause property, not at the top level of $ctx.error. You can verify this by temporarily adding a debug line to your response mapping template:

$util.toJson($ctx)

After running a test query, you'll see your custom statusCode, name, and message are nested inside $ctx.error.cause, while the top-level $ctx.error is an AppSync-generated wrapper error. That's why your original template wasn't finding the properties.

2. Fix the Response Mapping Template #

Update your template to pull the custom error from $ctx.error.cause, and correct the $util.error usage (note: it's $util, not $utils—you had a typo earlier):

#if (!$util.isNull($ctx.error))
  #set($customError = $ctx.error.cause)
  $util.error(
    $customError.message,
    $customError.name,
    null,
    {
      "statusCode": $customError.statusCode,
      "message": $customError.message
    }
  )
#end
$util.toJson($ctx.result)

Key notes here:

• The fourth parameter of $util.error is the errorInfo object—this is where your custom properties will live in the GraphQL response, and unlike the data parameter, it won't be filtered by the query's selection set.
• If you're using callbacks in your Lambda instead of async/await, make sure you're throwing the error directly rather than passing it to the callback—this ensures AppSync receives the full error structure.

3. Ensure Your Custom Error Serializes Correctly in Lambda #

Node.js can sometimes strip custom properties from Error objects during serialization. Fix this by adding a toJSON method to your custom error class to explicitly include your properties:

export class ErrorWithStatusCode extends Error {
  public statusCode: number;
  constructor({ message, name, statusCode, }: { message: string; name: string; statusCode: number; }) {
    super(message);
    this.name = name;
    this.statusCode = statusCode;
    // Fix prototype chain to avoid serialization issues
    Object.setPrototypeOf(this, ErrorWithStatusCode.prototype);
  }

  // Custom serialization to include all properties
  toJSON() {
    return {
      name: this.name,
      message: this.message,
      statusCode: this.statusCode,
      stack: this.stack
    };
  }
}

This ensures when Lambda serializes the error to send to AppSync, all your custom attributes are preserved.

4. Verify AppSync Data Source Configuration #

Double-check your Lambda data source settings in AppSync:

• Make sure "Lambda error handling" is set to allow error propagation (not suppressing errors or using a custom handler that might alter the error structure).
• If you're using batch operations, ensure the error handling for batches doesn't overwrite your custom error details.

After making these changes, your GraphQL response should include the custom statusCode in the errorInfo field, like this:

{ 
  "data": null, 
  "errors": [ 
    { 
      "path": [ "createResource" ], 
      "data": null, 
      "errorType": "BAD_REQUEST", 
      "errorInfo": { 
        "message": "An account with the email address already exists",
        "statusCode": 400
      }, 
      "locations": [ 
        { 
          "line": 2, 
          "column": 5, 
          "sourceName": null 
        } 
      ], 
      "message": "An account with the email address already exists" 
    } 
  ] 
}

内容的提问来源于stack exchange，提问作者Borduhh