AWS AppSync VTL模板空响应问题：需自定义错误返回格式

问题根源 #

当携带无效数据调用updateForm mutation时，虽然你的VTL模板用$utils.appendError捕获了错误，但因为模板未返回符合Schema（Form类型）的有效输出，导致AppSync抛出**"Template transformation yielded an empty response"**的模板错误，而非预期的400状态码和自定义错误信息。由于Schema定义mutation返回Form类型，Resolver必须要么返回Form对象，要么通过正确的错误抛出逻辑让AppSync处理响应。

解决方案 #

1. 修正响应映射模板的错误处理逻辑 #

在Response Mapping Template中，检测到无效数据（比如API返回非200状态码、无可用变更）时，需同时完成两步操作：

• 用$utils.appendError构造包含自定义信息和状态码的错误
• 返回符合Schema要求的空值（null），避免模板输出为空

示例VTL代码：

#if($ctx.result.statusCode != 200 || $ctx.result.body == "No changes")
  #set($errMsg = "No changes that can be applied to the form")
  #set($errCode = "400")
  # 附加错误信息，第三个参数传入自定义statusCode元数据
  $utils.appendError($errMsg, $errCode, {"statusCode": $errCode})
  # 返回null匹配Schema的Form类型要求
  null
#else
  # 正常返回转换后的Form数据
  $utils.toJson($ctx.result.body)
#end

2. 客户端接收的响应格式 #

修正后，客户端会收到包含正确错误信息的响应：

{
  "data": {
    "updateForm": null
  },
  "errors": [
    {
      "message": "No changes that can be applied to the form",
      "errorType": "400",
      "errorInfo": {
        "statusCode": "400"
      }
    }
  ]
}

3. 验证与排查 #

• 检查CloudWatch日志，确认$utils.appendError已被触发，且模板最终返回了null而非空内容
• 确保模板中调用$utils.appendError后立即返回null，避免后续逻辑导致输出为空

核心要点 #

• AppSync Resolver强制要求输出匹配Schema定义的类型，即使抛出错误，也不能让模板输出为空，否则会触发模板转换错误
• $utils.appendError的第三个参数可附加自定义元数据（如statusCode），方便客户端识别错误状态

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