RequestTooLargeException

Start Here

Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.

This page is part of the Error Reference library. Learn more about the project or report a correction.

What Does Request Too Large Mean?

RequestTooLargeException is a hard payload size ceiling - Lambda does not execute the function and returns this error immediately. The limit applies to the entire request payload including all headers and body content. Applications that pass large datasets, file contents, or uncompressed JSON blobs directly to Lambda invocations will hit this limit and must redesign the data passing pattern.

Common Causes

• -API Gateway passes a large file upload or uncompressed JSON payload directly to a Lambda function as the invocation event, exceeding the 6MB synchronous invocation limit.
• -Step Functions workflow passes accumulated state between Lambda steps as the event payload - state grows across steps until it exceeds the 256KB async invocation limit.
• -Application invokes Lambda asynchronously to process a large dataset by embedding the data directly in the event payload rather than passing a reference to S3 or another storage service.

How to Fix Request Too Large

1. 1Replace large inline payloads with an S3 reference - upload the data to S3 and pass only the bucket name and key in the Lambda event, letting the function fetch the data directly from S3.
2. 2For API Gateway file uploads, configure API Gateway to store the upload in S3 using a service integration and pass the S3 object reference to Lambda rather than the file contents.
3. 3Compress the event payload before invocation if the data cannot be externalized - gzip compression can reduce JSON payloads significantly and keep them under the limit.

Step-by-Step Diagnosis for Request Too Large

1. 1Measure the size of the payload being passed to Lambda - log the payload size before invocation and compare against the 6MB sync or 256KB async limit.
2. 2Identify the data source causing the oversized payload - file upload content, accumulated Step Functions state, large query results, or uncompressed JSON blobs.
3. 3Check whether the invocation is synchronous or asynchronous - async invocations have a much stricter 256KB limit that is easy to exceed with moderate-sized payloads.
4. 4Review the data flow design to identify where large datasets can be externalized to S3, DynamoDB, or another storage service instead of passing through Lambda event payloads.

# Upload file to S3 first
aws s3 cp large-dataset.json s3://my-bucket/inputs/large-dataset.json

# Invoke Lambda with S3 reference instead of file contents
aws lambda invoke \
  --function-name process-dataset \
  --payload '{"s3Bucket":"my-bucket","s3Key":"inputs/large-dataset.json"}' \
  --cli-binary-format raw-in-base64-out \
  response.json

import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';

const s3 = new S3Client({ region: 'us-east-1' });
const lambda = new LambdaClient({ region: 'us-east-1' });

async function processLargeDataset(data) {
  const key = `inputs/${Date.now()}-dataset.json`;

  // Store large data in S3
  await s3.send(new PutObjectCommand({
    Bucket: 'my-bucket',
    Key: key,
    Body: JSON.stringify(data),
  }));

  // Pass only S3 reference to Lambda
  const response = await lambda.send(new InvokeCommand({
    FunctionName: 'process-dataset',
    Payload: JSON.stringify({ s3Bucket: 'my-bucket', s3Key: key }),
  }));
  return response;
}

import boto3
import json
from datetime import datetime

s3 = boto3.client('s3', region_name='us-east-1')
lambda_client = boto3.client('lambda', region_name='us-east-1')

def invoke_with_large_payload(function_name, large_data, bucket='my-bucket'):
    # Upload large data to S3
    key = f'inputs/{datetime.utcnow().isoformat()}-payload.json'
    s3.put_object(
        Bucket=bucket,
        Key=key,
        Body=json.dumps(large_data),
    )
    # Invoke Lambda with S3 reference only
    response = lambda_client.invoke(
        FunctionName=function_name,
        Payload=json.dumps({'s3Bucket': bucket, 's3Key': key}),
    )
    return response

Seen in Production

Debugging Tools

• -AWS CLI invoke with --log-type Tail to capture function execution start - absence of logs confirms rejection before execution
• -Payload size logging before invocation - measure JSON.stringify(payload).length and alert when approaching limits
• -AWS X-Ray - trace invocation requests to measure payload sizes across the call chain
• -Step Functions execution history - inspect state size at each step to identify where payload growth occurs

How to Verify the Fix

• -Re-invoke Lambda with the redesigned payload and confirm RequestTooLargeException no longer appears.
• -Verify the function correctly retrieves externalized data from S3 or another storage service and produces the expected output.
• -Measure the new payload size and confirm it has sufficient headroom below the applicable limit to accommodate future data growth.

How to Prevent Recurrence

• -Establish a payload size budget for each Lambda function and enforce it in code review - document the expected payload schema and maximum size so engineers know when to externalize data.
• -Add payload size assertions to Lambda integration tests that fail when the event exceeds a configurable threshold - catching oversized payloads in tests prevents RequestTooLargeException in production.
• -For Step Functions workflows, use the S3 pass-through pattern by default for any step that processes or produces data larger than a few kilobytes.

Pro Tip

Related Errors

Official References

• -AWS Lambda - Lambda quotas and limits
• -AWS - Claim check pattern for large payloads
• -AWS Step Functions - Handling large payloads
• -AWS Official Documentation