AWS EmulatorでSQSのデッドレターキューを試す方法
Amazon SQS のデッドレターキュー(DLQ)は、何度受け取っても処理が終わらないメッセージを、別のキューに移して分けておく仕組みです。失敗し続けるジョブのリトライに回数の上限を付け、処理できなかったメッセージを後から調べられるように取っておきたいときに使います。AWS Emulator を手元で動かすと、DLQ の設定、メッセージが移る瞬間、直したあとに元のキューへ戻す操作までを、AWS のアカウントなしで AWS CLI から確かめられます。
検証環境は Ubuntu 24.04(x86_64)、AWS Emulator 1.0.486(2026年11月17日リリース)、AWS CLI 2.40.4 です。AWS のアカウントと認証情報は使っていません。出力の12桁のアカウントIDは <12桁のアカウントID> に置き換えています。本物の Amazon SQS での動きと料金は確かめておらず、記事で触れるところは公式ドキュメントを出どころにしています。試したのは標準キューを DLQ にする場合だけで、FIFO キューの DLQ、Lambda や SNS から使う DLQ、移動の取り消し(CancelMessageMoveTask)、CloudWatch のアラーム、SDK からの呼び出しは試していません。
- 1. エミュレーターを起動して、AWS CLI を向ける
- 2. DLQ にするキューを先に作り、ARN を調べる
- 3. 元のキューに RedrivePolicy を付けて作る
- 4. 3回受け取って消さないと、次の受信で DLQ に移る
- 5. DLQ のメッセージから、どのキューで失敗したかを見る
- 6. 受け取ってすぐ消したメッセージは移らない
- 7. 処理を直したら、start-message-move-task で元のキューに戻す
- 8. 元のキューではなく、別のキューに移す
- 9. 設定を間違えたときに返るエラー
- 10. RedriveAllowPolicy で、DLQ を使える元のキューを絞る
- 11. 本物の SQS で DLQ を使うときに、公式ドキュメントが注意していること
エミュレーターを起動して、AWS CLI を向ける
AWS Emulator は公式の Linux 向けの手順のとおり、Debian パッケージを取得し、署名を確かめてから apt-get install で入れました。起動は aws-emulator で、-t off はテレメトリーを切る指定です。
aws-emulator -t off
エミュレーターを動かしたまま別の端末を開き、公式ドキュメントにある環境変数を設定して、AWS CLI の送り先をエミュレーターにし、認証情報もエミュレーターが作ったものを使うようにします。
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_CA_BUNDLE=~/.aws/emulator/9297/ca.pem
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE
公式ドキュメントにあるとおり、aws sts get-caller-identity の ARN が user/emulator になっていれば、エミュレーターに届いています。
$ aws sts get-caller-identity --query Arn --output text
arn:aws:iam::<12桁のアカウントID>:user/emulator
DLQ にするキューを先に作り、ARN を調べる
DLQ の説明のページによると、DLQ は先に普通のキューとして作っておき、元のキューの設定でそれを指します。DLQ は元のキューと同じ AWS アカウント、同じリージョンに置く必要があります。
DLQ 用のキュー example-dlq を作り、設定で使う ARN を取り出します。キューの URL は変数 DLQ に入れておきます。
$ aws sqs create-queue --queue-name example-dlq
{
"QueueUrl": "https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-dlq"
}
$ export DLQ=$(aws sqs get-queue-url --queue-name example-dlq --query QueueUrl --output text)
$ aws sqs get-queue-attributes --queue-url "$DLQ" --attribute-names QueueArn --query Attributes.QueueArn --output text
arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq
$ export DLQ_ARN=$(aws sqs get-queue-attributes --queue-url "$DLQ" --attribute-names QueueArn --query Attributes.QueueArn --output text)
元のキューに RedrivePolicy を付けて作る
元のキューには RedrivePolicy という属性で、移す先の DLQ の ARN(deadLetterTargetArn)と、何回受け取られたら移すか(maxReceiveCount)を設定します。SetQueueAttributes のリファレンスによると、maxReceiveCount の既定値は10で、メッセージの受信回数がこの値を超えると DLQ に移されます。
RedrivePolicy の値は、JSON をさらに文字列にしたものです。コマンドラインに直接書くとエスケープが込み入るので、ファイルに書いて file:// で渡しました。試しやすいように、maxReceiveCount は3、受け取ったメッセージが見えなくなる時間(VisibilityTimeout)は2秒にしています。下の cat は、実際には作業ディレクトリのパスを付け、アカウントIDを伏せる処理も通して実行しました。ここでは短く書き直しています。
$ cat dlq-attrs.json
{
"VisibilityTimeout": "2",
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq\",\"maxReceiveCount\":\"3\"}"
}
$ aws sqs create-queue --queue-name example-queue --attributes file://dlq-attrs.json
{
"QueueUrl": "https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue"
}
$ export Q=$(aws sqs get-queue-url --queue-name example-queue --query QueueUrl --output text)
設定を読み返すと、文字列の "3" で渡した maxReceiveCount が、数値の 3 になって返りました。
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names VisibilityTimeout RedrivePolicy
{
"Attributes": {
"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq\",\"maxReceiveCount\":3}",
"VisibilityTimeout": "2"
}
}
逆向きに、ある DLQ を指している元のキューの一覧は list-dead-letter-source-queues で出せます。
$ aws sqs list-dead-letter-source-queues --queue-url "$DLQ"
{
"queueUrls": [
"https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-queue"
]
}
3回受け取って消さないと、次の受信で DLQ に移る
処理に失敗し続けるメッセージの代わりに、受け取っても消さないメッセージを用意します。order-1001 を送り、受け取ったら消さずに3秒待つ操作を、4回繰り返しました。3秒は、見えなくなる時間の2秒が過ぎるのを待つためです。受信回数を見るため、ApproximateReceiveCount の属性も一緒に受け取ります。
$ aws sqs send-message --queue-url "$Q" --message-body "order-1001"
{
"MD5OfMessageBody": "929211f12c9f601477a81243838a056c",
"MessageId": "a8fcc294-4278-49f7-ae90-503037521e04"
}
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
a8fcc294-4278-49f7-ae90-503037521e04 order-1001 1
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
a8fcc294-4278-49f7-ae90-503037521e04 order-1001 2
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
a8fcc294-4278-49f7-ae90-503037521e04 order-1001 3
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
None
3回目までは同じメッセージが返り、受信回数が1ずつ増えました。4回目の受信では何も返らず(None)、メッセージは DLQ に移っていました。元のキューは空になり、DLQ に1件あります。
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessages": "0",
"ApproximateNumberOfMessagesNotVisible": "0"
}
}
$ aws sqs get-queue-attributes --queue-url "$DLQ" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessagesNotVisible": "0",
"ApproximateNumberOfMessages": "1"
}
}

DLQ のメッセージから、どのキューで失敗したかを見る
DLQ の中身は、普通のキューと同じく receive-message で見られます。見たあとも DLQ に置いておきたいので、--visibility-timeout 0 を付け、受け取ったメッセージがすぐに見える状態に戻るようにしました。
$ aws sqs receive-message --queue-url "$DLQ" --visibility-timeout 0 --message-system-attribute-names All
{
"Messages": [
{
"MessageId": "a8fcc294-4278-49f7-ae90-503037521e04",
"ReceiptHandle": "M2ZjYjgy…(省略)",
"MD5OfBody": "929211f12c9f601477a81243838a056c",
"Body": "order-1001",
"Attributes": {
"DeadLetterQueueSourceArn": "arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-queue",
"ApproximateFirstReceiveTimestamp": "1794900853138",
"SenderId": "AIDAH5I7GEMO7ADXNFAZU",
"SentTimestamp": "1794900852566",
"ApproximateReceiveCount": "4"
}
}
]
}
DeadLetterQueueSourceArn に、移る前にいたキューの ARN が入っていました。どのキューから移ってきたメッセージかを、この属性から確かめられます。MessageId は、元のキューに送ったときと同じでした。
ApproximateReceiveCount は 4 です。ReceiveMessage のリファレンスでは、この値は消されないまま受け取られた回数を、すべてのキューを通して数えたものと説明されています。DLQ で受け取った分も数えられていて、エミュレーターを起動し直して試したところ、DLQ で --visibility-timeout 0 を付けて受け取るたびに、4、5 と増えました。中身を見るだけのつもりでも、受信回数は増えます。
受け取ってすぐ消したメッセージは移らない
DLQ に移るのは、消されないまま受信が重なったメッセージだけです。処理がうまくいったときのように、受け取ったその受信ハンドルですぐ消せば、DLQ には何も増えません。受け取った本文と受信ハンドルをいったんファイルに書き、受信ハンドルを変数 RH に入れてから消しました。
$ aws sqs send-message --queue-url "$Q" --message-body "order-1002" --query MessageId --output text
ac6d84e1-9350-4528-8642-ac33174e970f
$ aws sqs receive-message --queue-url "$Q" --query "Messages[0].[Body,ReceiptHandle]" --output text > msg.txt; cut -f1 msg.txt
order-1002
$ export RH=$(cut -f2 msg.txt)
$ aws sqs delete-message --queue-url "$Q" --receipt-handle "$RH"
3秒待っても、元のキューは空のままで、DLQ も order-1001 の1件だけでした。
$ aws sqs get-queue-attributes --queue-url "$Q" --attribute-names ApproximateNumberOfMessages ApproximateNumberOfMessagesNotVisible
{
"Attributes": {
"ApproximateNumberOfMessages": "0",
"ApproximateNumberOfMessagesNotVisible": "0"
}
}
$ aws sqs get-queue-attributes --queue-url "$DLQ" --attribute-names ApproximateNumberOfMessages
{
"Attributes": {
"ApproximateNumberOfMessages": "1"
}
}
処理を直したら、start-message-move-task で元のキューに戻す
処理の不具合を直したあと、DLQ にたまったメッセージを元のキューへ戻す操作を、公式ドキュメントではデッドレターキューのリドライブと呼んでいます。API では StartMessageMoveTask で、--source-arn に DLQ の ARN を渡します。行き先(--destination-arn)を省くと、メッセージはそれぞれの元のキューに戻されます。
$ aws sqs start-message-move-task --source-arn "$DLQ_ARN"
{
"TaskHandle": "eyJ0YXNrSWQi…(省略)"
}
リファレンスによると、移動は非同期のタスクとして進むので、進み具合は list-message-move-tasks で確かめます。検証環境では、始めてすぐに確かめたときにはもう COMPLETED で、1件のうち1件が移っていました。
$ aws sqs list-message-move-tasks --source-arn "$DLQ_ARN"
{
"Results": [
{
"Status": "COMPLETED",
"SourceArn": "arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq",
"ApproximateNumberOfMessagesMoved": 1,
"ApproximateNumberOfMessagesToMove": 1,
"StartedTimestamp": 1794900874772
}
]
}
戻したメッセージを、また消さずに4回受け取ってみました。
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
a8fcc294-4278-49f7-ae90-503037521e04 order-1001 5
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
a8fcc294-4278-49f7-ae90-503037521e04 order-1001 6
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
a8fcc294-4278-49f7-ae90-503037521e04 order-1001 7
$ aws sqs receive-message --queue-url "$Q" --message-system-attribute-names ApproximateReceiveCount --query "Messages[].[MessageId,Body,Attributes.ApproximateReceiveCount]" --output text
None
$ aws sqs get-queue-attributes --queue-url "$DLQ" --attribute-names ApproximateNumberOfMessages
{
"Attributes": {
"ApproximateNumberOfMessages": "1"
}
}
エミュレーターでは、戻したあとも MessageId は同じで、受信回数は 5 から数え続けられました。それでも、戻してから3回受け取った次の受信で、また DLQ に移りました。処理が直っていなければ、戻しても同じように DLQ に戻ってきます。
公式ドキュメントのリドライブのページには、戻したメッセージは新しいメッセージとして扱われ、新しいメッセージ ID と、キューに入った時刻が付け直されると書かれています。エミュレーターでは MessageId が変わらなかったので、メッセージ ID で処理済みかどうかを判定するようなコードは、エミュレーターと本物の SQS とで結果が分かれます。
元のキューではなく、別のキューに移す
--destination-arn を付けると、DLQ のメッセージを元のキューではなく、指定したキューに移せます。リドライブのページによると、行き先のキューは DLQ と同じ種類(標準キューなら標準キュー)である必要があります。--max-number-of-messages-per-second は1秒あたりに移す件数で、StartMessageMoveTask のリファレンスでは上限が500です。
直前で DLQ に戻った order-1001 を、新しく作った example-retry-queue に移しました。キューの URL と ARN は、DLQ のときと同じやり方で変数 RETRY と RETRY_ARN に入れています。
$ aws sqs create-queue --queue-name example-retry-queue
{
"QueueUrl": "https://sqs.us-east-1.amazonaws.com/<12桁のアカウントID>/example-retry-queue"
}
$ aws sqs start-message-move-task --source-arn "$DLQ_ARN" --destination-arn "$RETRY_ARN" --max-number-of-messages-per-second 10 --query TaskHandle --output text > /dev/null; echo started
started
$ aws sqs list-message-move-tasks --source-arn "$DLQ_ARN" --query "Results[].[Status,DestinationArn,MaxNumberOfMessagesPerSecond,ApproximateNumberOfMessagesMoved]" --output text
COMPLETED arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-retry-queue 10 1
$ aws sqs receive-message --queue-url "$RETRY" --query "Messages[0].[Body,ReceiptHandle]" --output text > msg.txt; cut -f1 msg.txt
order-1001
example-retry-queue から order-1001 を受け取れました。受け取ったメッセージは受信ハンドルで消しました。このあと DLQ を確かめると、0件でした。
設定を間違えたときに返るエラー
RedrivePolicy の誤りは、キューを作る時点で InvalidParameterValue として断られました。どれも、ファイルに書いた属性を create-queue に渡しています。
存在しないキューを DLQ に指定したときは、Dead letter target does not exist. でした。
$ cat bad-missing.json
{"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:no-such-dlq\",\"maxReceiveCount\":\"3\"}"}
$ aws sqs create-queue --queue-name bad-missing --attributes file://bad-missing.json
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the CreateQueue operation: Value {"deadLetterTargetArn":"arn:aws:sqs:us-east-1:<12桁のアカウントID>:no-such-dlq","maxReceiveCount":"3"} for parameter RedrivePolicy is invalid. Reason: Dead letter target does not exist.
maxReceiveCount を 0 にすると、エミュレーターは1から1000までの値にするよう返しました。
$ cat bad-zero.json
{"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq\",\"maxReceiveCount\":\"0\"}"}
$ aws sqs create-queue --queue-name bad-zero --attributes file://bad-zero.json
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the CreateQueue operation: Value {"deadLetterTargetArn":"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq","maxReceiveCount":"0"} for parameter RedrivePolicy is invalid. Reason: Invalid value for maxReceiveCount: 0, valid values are from 1 to 1000 both inclusive.
FIFO キューから標準キューの DLQ を指すと、種類が合わないと断られました。SetQueueAttributes のリファレンスにも、FIFO キューの DLQ は FIFO キュー、標準キューの DLQ は標準キューでなければならないと書かれています。
$ cat bad-fifo.json
{"FifoQueue": "true", "RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq\",\"maxReceiveCount\":\"3\"}"}
$ aws sqs create-queue --queue-name bad-type.fifo --attributes file://bad-fifo.json
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the CreateQueue operation: Value {"deadLetterTargetArn":"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq","maxReceiveCount":"3"} for parameter RedrivePolicy is invalid. Reason: Dead-letter queue must be same type of queue as the source..
RedriveAllowPolicy で、DLQ を使える元のキューを絞る
DLQ の側には RedriveAllowPolicy という属性があり、どのキューからその DLQ を指してよいかを決められます。SetQueueAttributes のリファレンスによると、redrivePermission の値は、同じアカウント・同じリージョンのどのキューからでも指せる allowAll(既定)、どのキューからも指せない denyAll、sourceQueueArns に並べたキュー(10個まで)だけが指せる byQueue の3つです。
byQueue で example-queue だけを許可しました。
$ cat allow-byqueue.json
{"RedriveAllowPolicy": "{\"redrivePermission\":\"byQueue\",\"sourceQueueArns\":[\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-queue\"]}"}
$ aws sqs set-queue-attributes --queue-url "$DLQ" --attributes file://allow-byqueue.json
$ aws sqs get-queue-attributes --queue-url "$DLQ" --attribute-names RedriveAllowPolicy
{
"Attributes": {
"RedriveAllowPolicy": "{\"redrivePermission\":\"byQueue\",\"sourceQueueArns\":[\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-queue\"]}"
}
}
許可していない other-queue から同じ DLQ を指そうとすると、DLQ の RedriveAllowPolicy が許していないという理由で、キューを作れませんでした。
$ cat other-queue.json
{"RedrivePolicy": "{\"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq\",\"maxReceiveCount\":\"3\"}"}
$ aws sqs create-queue --queue-name other-queue --attributes file://other-queue.json
aws: [ERROR]: An error occurred (InvalidParameterValue) when calling the CreateQueue operation: Value RedrivePolicy(maxReceiveCount=3, deadLetterTargetArn=arn:aws:sqs:us-east-1:<12桁のアカウントID>:example-dlq) for parameter RedrivePolicy is invalid. Reason: The value for the dead-letter queue's RedriveAllowPolicy attribute prevents you from completing this request.
本物の SQS で DLQ を使うときに、公式ドキュメントが注意していること
DLQ の説明のページには、この記事のような短い検証では表に出てこない注意が書かれています。
標準キューでは、メッセージの保持期間は、最初に元のキューに入った時刻から数えられ、DLQ に移っても時刻は変わりません。たとえば元のキューに1日いたメッセージは、保持期間が4日の DLQ では3日で消えます。そのため、DLQ の保持期間は元のキューより長くしておくのがよいとされています。FIFO キューでは、DLQ に移った時点で時刻が付け直されます。
maxReceiveCount を1のように小さくすると、1回受け取りに失敗しただけで DLQ に移ります。リトライに十分な回数を見込んだ値にするよう勧められています。また、標準キューで maxReceiveCount が3より大きいときは、消されないまま3回以上受け取られたメッセージがキューの後ろに回されると書かれています。
AWS Emulator は、エミュレーターと AWS の動きがどこまで同じかを、サービスごとのスコアとして GitHub のリリースページに載せています。忠実度(Fidelity)のページによると、今いちばん本物に近いのはリソースを作ったり一覧を出したりする API で、メッセージの送受信のような部分はサービスによって差があります。この記事で見た MessageId の違いのように、送受信まわりには本物と違う動きもあるので、DLQ を使う処理は、エミュレーターで流れを確かめたうえで、本物の SQS でも確かめておくと安心です。





