CloudConsole

SQS visibility timeout

Updated 17 November 2026 · How we write and check guides

Short answer

The visibility timeout is how long a message stays hidden from other consumers after one consumer receives it: 30 seconds by default, 0 seconds to 12 hours allowed. If the message isn't deleted before it expires, it becomes visible again and is delivered a second time. Set it comfortably longer than your worst-case processing time; for a Lambda event source, AWS recommends at least six times the function timeout plus MaximumBatchingWindowInSeconds, and Lambda refuses a queue whose visibility timeout is shorter than the function timeout.

Timeline: What the visibility timeout does. Message hidden after receive: visibility timeout 30 s; Consumer A, 20 s…
Where this setting acts, with the default and allowed values from this page.

How it works

  1. A consumer calls ReceiveMessage; SQS returns the message and starts its visibility timer.
  2. While the timer runs, other ReceiveMessage calls don't return that message. It counts as in flight (ApproximateNumberOfMessagesNotVisible).
  3. The consumer processes it and calls DeleteMessage with the receipt handle. Done.
  4. If the timer runs out first, the message becomes visible again, its receive count goes up, and another consumer (or the same one) gets it. After maxReceiveCount receives it moves to the dead-letter queue, if one is configured.

The queue's VisibilityTimeout attribute is the default. A consumer can override it for one receive (--visibility-timeout on receive-message) or for one message already in flight with ChangeMessageVisibility, for example to extend a long job as it runs.

Recommended values

ConsumerVisibility timeout
Lambda event source mappingAt least 6 x function timeout + MaximumBatchingWindowInSeconds
Worker processing one message at a timep99 processing time x 2 to 3, plus retry back-off
Long, variable jobs (minutes to hours)Moderate value (such as 5 minutes) and a heartbeat that calls ChangeMessageVisibility while working
Very fast idempotent handlersDefault 30 s is usually fine

The "six times" guidance gives Lambda room to retry a batch that was throttled before the messages reappear. With a 30-second function timeout and a 10-second batch window that means at least 190 seconds.

Don't overshoot either: a 12-hour timeout means a message whose consumer crashed waits 12 hours before anyone retries it.

Change it

aws sqs set-queue-attributes --queue-url https://sqs.eu-west-2.amazonaws.com/123456789012/orders \
  --attributes VisibilityTimeout=180

aws sqs get-queue-attributes --queue-url https://sqs.eu-west-2.amazonaws.com/123456789012/orders \
  --attribute-names VisibilityTimeout ApproximateNumberOfMessagesNotVisible

# Extend one in-flight message by 10 minutes from now (heartbeat pattern)
aws sqs change-message-visibility --queue-url https://sqs.eu-west-2.amazonaws.com/123456789012/orders \
  --receipt-handle "AQEBwJnKyrHigUMZj6rYigCgxlaS3SLy0a..." --visibility-timeout 600

CloudFormation: VisibilityTimeout on AWS::SQS::Queue. Terraform: visibility_timeout_seconds on aws_sqs_queue. Console: queue, Edit, Configuration, Visibility timeout.

If you raise a Lambda function's timeout, raise the queue's visibility timeout first; updating the event source mapping or function fails if the function timeout would exceed the visibility timeout.

Symptoms of getting it wrong

SymptomCause
Same message processed two or more times, often concurrentlyVisibility timeout shorter than processing time
Messages land in the DLQ though the code succeeds eventuallyRepeated re-delivery consumed maxReceiveCount
Failed messages take hours to be retriedVisibility timeout far too long
ApproximateNumberOfMessagesNotVisible near 120,000 and receives return nothingIn-flight cap from slow deletes; see SQS limits
Lambda: "Queue visibility timeout ... is less than Function timeout" when creating the mappingRaise the queue's visibility timeout

Standard queues are at-least-once even with a correct timeout, so make handlers idempotent.

Questions

What is the default SQS visibility timeout?

30 seconds. It can be set from 0 seconds to 12 hours (43,200 seconds).

What should the SQS visibility timeout be for Lambda?

At least six times the function timeout, plus the batching window. Lambda won't create or update a mapping when the function timeout is longer than the queue's visibility timeout.

Can I change the visibility timeout for a single message?

Yes. Call ChangeMessageVisibility with the message's receipt handle to extend or shorten its timeout while it is in flight.

When this happens away from your desk

Duplicate processing from a short visibility timeout tends to appear only under load. CloudConsole, a phone app for AWS, is being built to show queue depth and age alarms on your phone so a backlog doesn't go unnoticed.

About the app → · Download on the App Store

Sources