API Gateway Image Optimization 502 Error with Response Streaming

[bestickley]

API Gateway Image Optimization 502 Error with Response Streaming

Problem

When using NextjsRegionalFunctions with API Gateway REST API, image optimization requests to /_next/image return 502 Bad Gateway errors when Lambda Web Adapter is configured with AWS_LWA_INVOKE_MODE: "response_stream".

Current Workaround

Setting AWS_LWA_INVOKE_MODE: "buffered" resolves the image issue but disables streaming for all routes:

nextjsApi: {
dynamicIntegrationProps: {
            responseTransferMode: ResponseTransferMode.BUFFERED,
          },
},
nextjsFunctions: {
  dockerImageFunctionProps: {
    environment: {
      AWS_LWA_INVOKE_MODE: "buffered",
    },
  },
},

Desired Behavior

• /_next/image route: Buffered (binary data compatibility)
• All other routes: Streaming (performance benefits for HTML/RSC)

What Was Tried

Attempt 1: Different Integration Modes per Route

Modified NextjsApi to use different LambdaIntegration configurations:

// Image route - buffered
const imageIntegration = new LambdaIntegration(serverFunction, {
  // No ResponseTransferMode.STREAM
});

// Other routes - streaming  
const streamingIntegration = new LambdaIntegration(serverFunction, {
  responseTransferMode: ResponseTransferMode.STREAM,
});

Result: Still getting 502 errors on /_next/image route

Attempt 2: Investigation Points

• Lambda completes successfully (logs show image optimization, caching to S3)
• 502 occurs after Lambda returns to API Gateway
• binaryMediaTypes: ["*/*"] is configured on REST API
• Cache handler stores images as JSON with Buffer serialization (UTF-8) which works correctly

Logs

Lambda logs show successful execution:

2026-01-23T02:51:29.112Z cdk-nextjs:proxy request.url: http://0.0.0.0:3000/prod/static/eniko-kis-KsLPTsYaqIQ-unsplash.jpg
2026-01-23T02:51:29.112Z cdk-nextjs:proxy { status: 200, statusText: '', body: null }
2026-01-23T02:51:29.329Z cdk-nextjs:cache-handler:memory MEMORY CACHE SET: DiIwMZnOiQPbxRayEvr9lo9P5I41YqIgVxViv7OwHRU (IMAGE)
2026-01-23T02:51:29.442Z cdk-nextjs:cache-handler:s3 S3 CACHE STORED: DiIwMZnOiQPbxRayEvr9lo9P5I41YqIgVxViv7OwHRU (IMAGE)
END RequestId: fd1e175e-ebe9-45db-b71e-dce054893bb5
REPORT RequestId: fd1e175e-ebe9-45db-b71e-dce054893bb5	Duration: 440.48 ms

But API Gateway returns:

< HTTP/2 502 
< content-type: application/json
< x-amzn-errortype: InternalServerErrorException
{"message": "Internal server error"}

Environment

• Next.js: 16.1.1-canary.19
• Lambda Web Adapter: latest (via Docker)
• API Gateway: REST API with regional endpoint
• CDK: aws-cdk-lib latest

Next Steps for Debugging

1. Enable API Gateway execution logs to see the actual error from Lambda integration
2. Test with a minimal Lambda function that returns binary data with streaming enabled to isolate if it's an API Gateway + streaming + binary issue
3. Check Lambda response format - ensure Lambda Web Adapter with response_stream returns responses in the format API Gateway expects for binary data
4. Investigate API Gateway streaming limitations - there may be documented restrictions on binary media types with response streaming
5. Try AWS_LWA_INVOKE_MODE as request header - investigate if Lambda Web Adapter can be controlled per-request instead of via environment variable
6. Consider Lambda Function URLs - they support response streaming and binary data natively, though would require different architecture

Code References

• API Gateway integration: src/nextjs-api.ts line 248-268
• Lambda Web Adapter config: src/nextjs-compute/nextjs-functions.ts line 62
• Workaround: examples/regional-functions/app.ts line 60

Related

• Lambda Web Adapter response streaming: https://github.com/awslabs/aws-lambda-web-adapter#response-streaming
• API Gateway binary media types: https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-payload-encodings.html

[bestickley]

  | 2026-01-23T03:55:11.409Z{     "requestId": "5a9afccd-2189-4a83-a1f0-6c0f16687c51",     "ip": "68.131.117.146",     "user": "-",     "caller": "-",     "requestTime": "23/Jan/2026:03:55:11 +0000",     "httpMethod": "GET",     "resourcePath": "/{proxy+}",     "status": "502",     "protocol": "HTTP/1.1",     "responseLength": "0",     "integrationError": "Execution failed due to configuration error: Response metadata exceeds maximum capacity 16384 bytes",     "integrationStatus": "-" }
-- | --