What the SQS visibility timeout does, how to pick a value, how to extend it with a heartbeat for long jobs, how it interacts with retries, Lambda and dead-letter queues, and how Encore sets it from a subscription's AckDeadline.

The SQS visibility timeout is how long a message stays hidden after a consumer receives it. SQS has no connection to notice a crashed worker, so it hands out a lease instead: delete the message before the lease runs out and it is done, let the lease expire and the message comes back for someone else. Set it too short and slow jobs run twice; set it too long and a crashed worker's messages sit invisible long after they could have been retried.
This guide explains how the timeout works, how to pick a value, how to extend it for long jobs and use it for retry backoff, how it interacts with Lambda and dead-letter queues, and how Encore sets it from a Pub/Sub subscription.
Figures are from the SQS visibility timeout guide and the SQS message quotas.
A message's life in SQS is receive, process, delete: ReceiveMessage returns the message with a receipt handle and starts its visibility timeout, and only the holder of that receipt handle can delete it or change its timeout. If DeleteMessage arrives in time, the message is gone. If the timeout expires first, because the worker crashed, hung or was slow, SQS makes the message visible again and increments its ApproximateReceiveCount.
The first consequence is that the timeout is the retry delay after a crash, since nothing else brings the message back, and the receive count is what a redrive policy compares with maxReceiveCount to move a message to the dead-letter queue. The second is that SQS delivers at least once even within the timeout: AWS notes that it does not guarantee a message will not be delivered more than once during the visibility timeout, so handlers have to be idempotent whatever value you pick.
FIFO queues add ordering to this: while a message from a message group is in flight, later messages in the same group are not delivered until it is deleted or its timeout expires, so a long timeout on a stuck message holds up its whole group.
Start from the slow case: measure the time to process and delete a message at the 99th percentile or worst normal case, and set the queue's timeout comfortably above it, since a timeout below the slow-case processing time turns slow jobs into duplicates and, eventually, into dead-lettered messages that never failed. If you have no data, AWS suggests starting with something like 2 minutes and adjusting.
For Lambda, the SQS event source docs recommend a queue visibility timeout of at least six times the function timeout, plus the batching window if you set one, so Lambda has time to retry a throttled batch before the messages reappear. A 30 second function therefore wants a queue timeout of 3 minutes or more.
When durations vary widely, for example a report that takes ten seconds for a small account and twenty minutes for a large one, a single value is either too short for the large job or far too long for crash recovery on the small one, which is where a heartbeat helps.
A heartbeat receives with a moderate timeout and calls ChangeMessageVisibility on a timer while the job runs, so a live worker keeps its lease and a dead one loses it within a minute. The same call doubles as retry backoff: on failure, set the visibility to the delay you want before the next attempt instead of waiting out the rest of the lease. A worker with the AWS SDK for Go v2:
// main.go
package main
import (
"context"
"log"
"os"
"strconv"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/sqs"
"github.com/aws/aws-sdk-go-v2/service/sqs/types"
)
const (
visibility = 60 * time.Second // the lease each receive or extension asks for
heartbeat = 20 * time.Second // extend well before the lease runs out
)
func main() {
ctx := context.Background()
cfg, err := config.LoadDefaultConfig(ctx)
if err != nil {
log.Fatal(err)
}
client := sqs.NewFromConfig(cfg)
queueURL := os.Getenv("QUEUE_URL")
for {
out, err := client.ReceiveMessage(ctx, &sqs.ReceiveMessageInput{
QueueUrl: aws.String(queueURL),
MaxNumberOfMessages: 1,
WaitTimeSeconds: 20,
VisibilityTimeout: int32(visibility.Seconds()),
MessageSystemAttributeNames: []types.MessageSystemAttributeName{types.MessageSystemAttributeNameApproximateReceiveCount},
})
if err != nil {
log.Printf("receive: %v", err)
time.Sleep(time.Second)
continue
}
for _, m := range out.Messages {
handle(ctx, client, queueURL, m)
}
}
}
func handle(ctx context.Context, client *sqs.Client, queueURL string, m types.Message) {
// Keep the message invisible while work is running.
hbCtx, stop := context.WithCancel(ctx)
defer stop()
go func() {
t := time.NewTicker(heartbeat)
defer t.Stop()
for {
select {
case <-hbCtx.Done():
return
case <-t.C:
_, err := client.ChangeMessageVisibility(hbCtx, &sqs.ChangeMessageVisibilityInput{
QueueUrl: aws.String(queueURL),
ReceiptHandle: m.ReceiptHandle,
VisibilityTimeout: int32(visibility.Seconds()),
})
if err != nil {
log.Printf("extend %s: %v", aws.ToString(m.MessageId), err)
}
}
}
}()
if err := process(ctx, aws.ToString(m.Body)); err != nil {
stop()
// Retry with backoff instead of waiting out the full lease.
n, _ := strconv.Atoi(m.Attributes[string(types.MessageSystemAttributeNameApproximateReceiveCount)])
delay := min(10*time.Second<<min(max(n-1, 0), 6), 10*time.Minute)
if _, err := client.ChangeMessageVisibility(ctx, &sqs.ChangeMessageVisibilityInput{
QueueUrl: aws.String(queueURL),
ReceiptHandle: m.ReceiptHandle,
VisibilityTimeout: int32(delay.Seconds()),
}); err != nil {
log.Printf("backoff %s: %v", aws.ToString(m.MessageId), err)
}
return
}
stop()
if _, err := client.DeleteMessage(ctx, &sqs.DeleteMessageInput{
QueueUrl: aws.String(queueURL),
ReceiptHandle: m.ReceiptHandle,
}); err != nil {
log.Printf("delete %s: %v", aws.ToString(m.MessageId), err)
}
}
func process(ctx context.Context, body string) error {
return nil // your work here
}
Each extension sets a new timeout from the moment of the call, so the heartbeat interval must be well under the extension, and the total still cannot pass 12 hours from the first receive. Work that can take longer than that belongs in Step Functions or in smaller messages. Each receive returns a new receipt handle, and once a lease has expired and the message has been received again, calls with the old handle can fail, so treat a failed extension as a sign that another worker may now own the message.
Encore brings infrastructure from code to messaging on AWS: a Pub/Sub topic declared in Go or TypeScript becomes an SNS topic, and each subscription gets its own SQS queue and dead-letter queue in your account, as the AWS infrastructure docs describe. The receive loop, deletes and backoff above are part of the runtime, and the settings that drive them live on the subscription.
Run in your terminal to get started locally.
// reports/reports.go
package reports
import (
"context"
"time"
"encore.dev/beta/errs"
"encore.dev/pubsub"
"encore.dev/rlog"
)
type ReportRequested struct {
ReportID string `json:"report_id"`
AccountID string `json:"account_id"`
Month string `json:"month"`
}
var Requested = pubsub.NewTopic[*ReportRequested]("report-requested", pubsub.TopicConfig{
DeliveryGuarantee: pubsub.AtLeastOnce,
})
// On AWS, AckDeadline becomes the SQS visibility timeout for this subscription's
// queue and the deadline on the handler's context.
var _ = pubsub.NewSubscription(Requested, "build-monthly-report", pubsub.SubscriptionConfig[*ReportRequested]{
Handler: buildReport,
AckDeadline: 10 * time.Minute,
MaxConcurrency: 4,
RetryPolicy: &pubsub.RetryPolicy{
MinBackoff: 30 * time.Second,
MaxBackoff: 10 * time.Minute,
MaxRetries: 4,
},
})
type RequestParams struct {
ReportID string `json:"report_id"`
AccountID string `json:"account_id"`
Month string `json:"month"`
}
//encore:api public method=POST path=/reports
func Request(ctx context.Context, p *RequestParams) error {
if _, err := time.Parse("2006-01", p.Month); err != nil || p.ReportID == "" {
return &errs.Error{Code: errs.InvalidArgument, Message: "report_id and month (YYYY-MM) are required"}
}
_, err := Requested.Publish(ctx, &ReportRequested{ReportID: p.ReportID, AccountID: p.AccountID, Month: p.Month})
return err
}
func buildReport(ctx context.Context, r *ReportRequested) error {
if deadline, ok := ctx.Deadline(); ok {
rlog.Info("building report", "report", r.ReportID, "time_left", time.Until(deadline).Round(time.Second).String())
}
// Long work should check ctx between steps and stop when it is done:
// returning an error schedules a retry after the backoff.
for _, step := range []string{"query", "render", "upload"} {
if err := ctx.Err(); err != nil {
return err
}
rlog.Info("report step", "report", r.ReportID, "step", step)
}
return nil
}
The handler sees a context deadline equal to AckDeadline, and on AWS the Go runtime receives from the subscription's queue with that value as the visibility timeout, long polling for 20 seconds at a time and clamping the deadline to between 1 second and 12 hours. When the handler returns nil, the message is deleted. When it returns an error, the runtime calls ChangeMessageVisibility with the backoff from the RetryPolicy, starting at MinBackoff and growing to MaxBackoff, which is the backoff branch of the hand-written worker, and after MaxRetries the message ends up in the dead-letter queue.
The runtime does not run a heartbeat, so AckDeadline is the budget for a single attempt: set it above the slowest normal run, and have long handlers check ctx.Err() between steps, as the example does, so they stop cleanly when the deadline passes instead of running on while the message is redelivered. Handlers should still be idempotent, since delivery is at least once.
Best fit: teams on AWS that want visibility timeouts, retry backoff and dead-letter queues set per subscription in code.
A redrive policy counts receives, not failures: a message that times out three times because the job is slow looks the same to SQS as one that failed three times, so with maxReceiveCount set to 3 and a timeout below your slow case, healthy work ends up in the DLQ. Set the timeout from the slow case first, then pick maxReceiveCount for real failures, and alarm on ApproximateNumberOfMessagesVisible on the DLQ. The SQS dead-letter queue guide covers redrive and replay.
It is how long a message stays hidden from other consumers after one consumer receives it. If the consumer deletes the message within that time, it is gone; if not, it becomes visible again and can be received by any consumer. The default is 30 seconds, the minimum 0 and the maximum 12 hours.
Set it above the time your consumer needs to process and delete a message in the slow case, not the average. For Lambda consumers AWS recommends at least six times the function timeout, plus the batching window if you use one. For jobs whose duration varies widely, use a shorter timeout and extend it with ChangeMessageVisibility while the job runs.
The message becomes visible again and another consumer can receive it while the first one is still working, so the same message is processed twice. Its receive count also goes up, so a slow but healthy job can end up in the dead-letter queue once it passes maxReceiveCount.
An Encore Pub/Sub subscription's AckDeadline, 30 seconds by default, becomes the visibility timeout on the subscription's SQS queue and the deadline on the handler's context. When the handler returns an error, Encore changes the message's visibility to the retry backoff from the subscription's RetryPolicy, and after MaxRetries the message goes to the dead-letter queue.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.