CloudConsole

aws lambda update-event-source-mapping

Updated 16 November 2026 · How we write and check guides

Short answer

aws lambda update-event-source-mapping --uuid <mapping UUID> --no-enabled pauses a Lambda trigger such as an SQS queue or Kinesis stream without deleting it; --enabled resumes it. The same command changes batch size, batching window, maximum concurrency, filters and retry settings. Find the UUID with list-event-source-mappings.

Terminal running UUID=$(aws lambda list-event-source-mappings…
A worked example from this page. Copy commands from the text below, not from the image.

What the command does

Event source mappings are identified by a UUID, not by name. This command changes the settings of an existing mapping in place. While the change applies, the mapping's State shows Updating, then returns to Enabled or Disabled. Some settings, such as the starting position of a stream, cannot be changed at all; for those you delete and recreate the mapping.

Syntax

aws lambda list-event-source-mappings --function-name my-function \
  --query "EventSourceMappings[].[UUID,EventSourceArn,State]" --output table

aws lambda update-event-source-mapping --uuid 14e0db71-0000-4eb5-b481-1945cf9d10c2 \
  [--enabled] [--no-enabled] [--batch-size 50] \
  [--maximum-batching-window-in-seconds 10] \
  [--scaling-config MaximumConcurrency=5] \
  [--filter-criteria ...] [--function-name my-function:live]

Worked examples

Pause processing during an incident, for example while a downstream API is failing:

UUID=$(aws lambda list-event-source-mappings --function-name orders-worker \
  --event-source-arn arn:aws:sqs:eu-west-2:123456789012:orders \
  --query "EventSourceMappings[0].UUID" --output text)
aws lambda update-event-source-mapping --uuid "$UUID" --no-enabled

For SQS, messages simply accumulate in the queue. Watch the retention period: messages older than it are deleted by SQS.

Resume:

aws lambda update-event-source-mapping --uuid "$UUID" --enabled

Slow it down instead of stopping, protecting a database while still draining the queue:

aws lambda update-event-source-mapping --uuid "$UUID" --scaling-config MaximumConcurrency=2

Increase throughput with bigger batches and a short batching window:

aws lambda update-event-source-mapping --uuid "$UUID" \
  --batch-size 100 --maximum-batching-window-in-seconds 5

For SQS, batch sizes above 10 require a batching window greater than zero.

Point the trigger at an alias so releases go through alias moves:

aws lambda update-event-source-mapping --uuid "$UUID" --function-name orders-worker:live

Stop a poison batch blocking a Kinesis shard by limiting retries and adding a destination:

aws lambda update-event-source-mapping --uuid "$UUID" \
  --maximum-retry-attempts 2 --bisect-batch-on-function-error \
  --destination-config '{"OnFailure":{"Destination":"arn:aws:sqs:eu-west-2:123456789012:clicks-dlq"}}'

Pause options compared

MethodEffect
--no-enabled on the mappingPolling stops; messages and records stay in the source.
Reserved concurrency 0 on the functionPolling may continue while invocations are throttled; SQS messages can move to the DLQ after repeated receives.
MaximumConcurrency=2Keeps draining slowly; SQS only.
delete-event-source-mappingRemoves the trigger; stream position is lost.

Gotchas

  • Changes are not instant. In-flight batches finish, and a disabled mapping can take a short while to stop polling.
  • ResourceInUseException means a previous update is still being applied; wait until State is no longer Updating.
  • Stream iterator age grows while paused. If records age beyond the stream's retention, they are lost.
  • Infrastructure as code drift. A paused mapping will be re-enabled by the next CloudFormation or Terraform deploy if the template says enabled.
  • Find mappings from the source side. aws lambda list-event-source-mappings --event-source-arn with a queue or stream ARN lists every function consuming it, which helps when you know the queue but not the function.

Questions

How do I disable a Lambda SQS trigger temporarily?

Run update-event-source-mapping --uuid <id> --no-enabled. Messages stay in the queue until you re-enable it with --enabled.

How do I find the UUID of an event source mapping?

aws lambda list-event-source-mappings --function-name my-function --query "EventSourceMappings[].[UUID,EventSourceArn]" --output table.

Can I change the starting position of a Kinesis trigger?

No. Delete the mapping and create a new one with the starting position you need.

When this happens away from your desk

Pausing a trigger is a common incident lever when something downstream is failing. CloudConsole, a phone app for AWS, is built to show queue depth, errors and logs on a phone, with guardrails around changes like this.

About the app → · Download on the App Store

Sources