API Gateway二进制请求转换失败问题及临时修复原因咨询

I’ve run into this exact issue before when setting up binary file uploads with Serverless and API Gateway, so let’s break down why that manual save fixes things and better ways to avoid the problem altogether.

Why Saving the Lambda Integration Request Fixes the Error #

That quick edit-and-save action does more than you might think—it forces API Gateway to fully sync its configuration and resolve inconsistencies that slipped through during the Serverless deployment:

• Configuration Sync Gap: The serverless-apigw-binary plugin updates API Gateway's Binary Media Types settings, but sometimes the link between those binary settings and your Lambda integration's request templates doesn’t get properly registered. API Gateway might still try to process the binary payload using default text-based transformations, leading to the "Unable to transform request" error. Saving the integration triggers a full refresh of how the gateway handles payloads for that endpoint.
• CloudFormation Asynchronous Delay: Serverless uses CloudFormation to deploy resources, and while the stack might show as "completed," API Gateway often has behind-the-scenes asynchronous configuration updates. Manually saving the integration bypasses this delay and ensures all settings are immediately active.
• Metadata Regeneration: The save action regenerates the integration's internal metadata, including validating that the request template for application/pdf is correctly associated with binary payload handling. Without this, the gateway can’t map the binary body to your template’s $input.body variable properly.

Better Solutions to Avoid Manual Fixes #

Instead of relying on manual console edits every deploy, use these automated approaches:

1. Configure Binary Media Types Directly via CloudFormation #

Skip the plugin entirely and define binary types directly in your Serverless CloudFormation resources. This removes any potential plugin-related sync issues:

resources:
  Resources:
    ApiGatewayRestApi:
      Type: AWS::ApiGateway::RestApi
      Properties:
        Name: ${self:service}
        BinaryMediaTypes:
          - 'application/pdf'

This ensures binary settings are part of the core CloudFormation stack, so they deploy consistently with the rest of your resources.

2. Add a Post-Deploy Hook to Refresh the Integration #

Use Serverless hooks to run an AWS CLI command after deployment that updates the Lambda integration, forcing a configuration refresh. Add this to your serverless.yml:

custom:
  apiId: ${sls:info.apiId}
  resourceId: ${sls:info.resources[0].id} # Adjust this to match your /upload resource ID

hooks:
  after:deploy:deploy:
    - aws apigateway update-integration --rest-api-id ${self:custom.apiId} --resource-id ${self:custom.resourceId} --http-method PUT --patch-operations op="replace",path="/passthroughBehavior",value="WHEN_NO_TEMPLATES"

Note: Adjust the resourceId variable to correctly reference your /upload resource—you can get the exact ID from sls info output after the first deploy.

3. Update the Serverless APIGW Binary Plugin #

Make sure you’re using the latest version of serverless-apigw-binary—many configuration sync bugs have been fixed in recent releases. Run:

npm update serverless-apigw-binary

Double-check your plugin configuration to ensure the types array matches exactly the content types you’re using (no extra spaces, correct casing).

Final Notes #

The manual save works because it’s a quick way to kick API Gateway into revalidating its entire integration configuration. For production setups, though, automated fixes are critical to avoid deployment delays or manual intervention.

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