Visibility Timeout: Preventing Double Work

The "Invisible" Message

When a consumer (a Lambda function, an EC2 instance, or an ECS task) polls a message from SQS, the message is not deleted from the queue. SQS uses a two-phase approach: first hide the message, then delete it only after the consumer confirms success. This protects against consumer crashes.

The period during which the message is hidden from all other consumers is called the Visibility Timeout. The default is 30 seconds. The maximum is 12 hours.

The Full Flow

1. T=0s: Consumer A calls ReceiveMessage. SQS returns Message X and starts the Visibility Timeout timer. Message X is now invisible to all other consumers.
2. T=0s to Timeout: Consumer A processes the job.
3. Success path: Consumer A finishes at T=5s and calls DeleteMessage with the receipt handle SQS provided. Message X is permanently removed. Done.
4. Crash path: Consumer A crashes at T=10s. It never calls DeleteMessage.
5. T=30s: The Visibility Timeout expires. Message X reappears in the queue as if nothing happened.
6. T=31s: Consumer B polls the queue, receives Message X, and retries processing.

This mechanism is what makes SQS resilient to consumer failures — messages are never truly lost unless explicitly deleted.

Setting the Right Visibility Timeout

The critical rule: the Visibility Timeout must be longer than the maximum time your consumer could take to process a single message.

If your Lambda function has a 15-minute timeout and processes large files, set the Visibility Timeout to at least 15 minutes. A common mistake is leaving it at the 30-second default.

For variable-duration jobs, consumers can call ChangeMessageVisibility to extend the timeout while they're still working — a heartbeat pattern that prevents premature re-queuing for long-running tasks.