As of November 16, 2026, this post sums up the official pages linked here.
The problem
A job runs twice. A customer is charged twice. Two workers write the same row. The first worker is still working when it happens. The queue is Amazon SQS, and the usual cause is not a "bug in SQS" so much as a visibility timeout that ran out before the first worker finished and deleted the message.
Our team at CloudSkill Consulting LLC sees this in reviews of worker services. In this post we show what the timeout does, how to set it, how to extend it while a long job is still running, and the hard 12-hour limit AWS documents.
Root cause: the message stays in the queue, it just goes hidden
When a consumer receives a message, AWS says the message "remains in the queue but becomes temporarily invisible to other consumers." That hidden period is the visibility timeout. You are expected to process the message and delete it during that period. If you do not delete it before the timeout ends, "the message becomes visible again in the queue and can be retrieved by another consumer." (Amazon SQS visibility timeout)
The default visibility timeout for a queue is 30 seconds. You can set a queue-level value from 0 to 43,200 seconds (12 hours). (set-queue-attributes in the AWS CLI Command Reference)
A 30-second default is short for many jobs: a report, a thumbnail, a call to another API that is slow. The first worker is still busy, the timeout ends, and a second worker receives the same message.
Step 1: set the queue timeout to match the work
AWS's own guidance is to start by setting the visibility timeout "to match the maximum time your application typically needs to process and delete a message." If you are not sure, they suggest starting shorter (they use two minutes as an example) and extending as needed. (Amazon SQS visibility timeout)
This sets the queue default to five minutes (300 seconds). Use your own queue URL and a value that fits your job:
aws sqs set-queue-attributes \ --queue-url "$QUEUE_URL" \ --attributes VisibilityTimeout=300 The attribute name and the 0-to-43,200 range come from the set-queue-attributes reference. This changes the queue default. It does not change a message that is already in flight.
Step 2: extend the timeout while a long message is still being processed
If one message needs more time than the queue default, AWS documents the ChangeMessageVisibility action: you can extend or shorten the timeout for that message. The AWS CLI form is:
aws sqs change-message-visibility \ --queue-url "$QUEUE_URL" \ --receipt-handle "$RECEIPT_HANDLE" \ --visibility-timeout 60 AWS also describes a heartbeat: extend the timeout from time to time so the message stays hidden until work is done. (Amazon SQS visibility timeout)
Two limits matter:
- The visibility timeout has a maximum of 12 hours from when the message is first received. Extending it does not reset that 12-hour clock. If the work needs longer, AWS suggests Step Functions or breaking the task into smaller steps. (same page)
- If you try to set a value greater than the time left under that limit, "Amazon SQS returns an error" and does not raise the timeout for you. (change-message-visibility)
One more surprise: a ChangeMessageVisibility value is not stored as the message's new default. If you do not delete the message and it is received again, AWS says the timeout "reverts to the original timeout value (not to the value you set using the ChangeMessageVisibility action)." (same CLI page)
The receipt handle is for that receive. Use the handle from the current receive, not an old one.
Step 3: send repeated failures to a dead-letter queue
If a message keeps failing, AWS recommends a dead-letter queue (DLQ) so those messages are "captured separately for further analysis or handling, preventing them from repeatedly circulating in the main queue." (Amazon SQS visibility timeout)
That stops a poison message from being processed over and over, which is a different problem from a timeout that is simply too short — but the two often show up in the same incident.
When it still goes wrong
- The timeout is still shorter than the job. Raise the queue default, add a heartbeat, or both.
- The job can run longer than 12 hours from first receive. The 12-hour cap cannot be extended past that point. Split the work or move it to a service meant for long runs, as AWS notes.
- Two valid workers both complete the job. Even after you fix the timeout, design the worker so a second delivery does not do the side effect twice. The visibility-timeout page's whole point is that a second consumer can receive the message if the first one does not delete it in time.
- You hit the in-flight limit. For most standard queues, AWS describes a limit of about 120,000 in-flight messages (received but not yet deleted). If you reach it,
OverLimitcan be returned and no more messages are received until some in-flight messages are deleted. (change-message-visibility, which restates this queue limit)
What to check first
- What is the queue's
VisibilityTimeout, and how long does a typical (and a slow) job actually take? - Does the worker delete the message only after the work succeeds?
- For long jobs, is there a heartbeat that calls
ChangeMessageVisibility, and does it respect the 12-hour cap? - Is a dead-letter queue in place for messages that fail repeatedly?
Sources
Every page below was read on Nov. 16, 2026.
- Amazon SQS Developer Guide, Amazon SQS visibility timeout (hidden period; default 30 seconds; message becomes visible again if not deleted; setting the timeout to match processing time; heartbeat; 12-hour limit from first receive; dead-letter queues): https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html
- AWS CLI Command Reference,
set-queue-attributes(VisibilityTimeoutvalid values 0 to 43,200 seconds, default 30): https://docs.aws.amazon.com/cli/latest/reference/sqs/set-queue-attributes.html - AWS CLI Command Reference,
change-message-visibility(minimum 0 seconds, maximum 12 hours; error if the value is greater than the time left; timeout reverts on the next receive; in-flight limit): https://docs.aws.amazon.com/cli/latest/reference/sqs/change-message-visibility.html
CloudSkill Consulting LLC helps teams with fixed-fee cloud projects, FinOps reviews and IT staffing. Learn more at cloudskillconsulting.com.