n8n Queue Mode AWS SQS Integration Error

Who this is for: Developers and DevOps engineers running n8n in production who need reliable, secure communication between n8n workers and Amazon SQS. We cover this in detail in the n8n Queue Mode Errors Guide.

---

Featured Snippet

1. Validate credentials – AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY must have sqs:* on the exact queue ARN.
2. Match region – AWS_REGION must be the same region that appears in SQS_QUEUE_URL.
3. Test connectivity – run aws sqs get-queue-attributes --queue-url $SQS_QUEUE_URL from the n8n host.
4. Fix any mismatch – adjust IAM policy, region, or network settings, then restart the n8n worker.

---

Quick Diagnosis

Symptom	Typical Fix
InvalidAccessKeyId	Re‑enter the correct access key; ensure the IAM user is active.
SignatureDoesNotMatch	Sync server time (NTP) and verify the region matches the queue URL.
QueueDoesNotExist	Correct the queue URL or use the right AWS account.
AccessDenied	Attach the minimal policy shown in Section 3.
Network timeout	Open outbound HTTPS (443) or configure a VPC endpoint for SQS.

---

1. How n8n Queue Mode Uses AWS SQS ?

Component	Role
n8n Worker	Pulls jobs from SQS, executes them, pushes results back (QUEUE_MODE=aws-sqs).
SQS Queue	Stores serialized workflow execution payloads (Standard or FIFO).
IAM User / Role	Authenticates API calls (sqs:SendMessage, sqs:ReceiveMessage, …).
Environment Variables	Provide credentials & queue metadata (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, SQS_QUEUE_URL).

EEFA note – In production, prefer an IAM role attached to the EC2/ECS task instead of static keys. This prevents credential leakage and enables automatic rotation.

---

2. Minimal IAM Policy for n8n Workers

Below are two focused snippets that together form the complete policy.

Snippet 1 – Policy skeleton (4 lines):

{
  "Version": "2012-10-17",
  "Statement": [

Snippet 2 – Permissions block (5 lines):

    {
      "Effect": "Allow",
      "Action": [
        "sqs:SendMessage",
        "sqs:ReceiveMessage",
        "sqs:DeleteMessage",
        "sqs:GetQueueAttributes",
        "sqs:ChangeMessageVisibility"
      ],

Snippet 3 – Resource ARN (4 lines):

      "Resource": "arn:aws:sqs:${AWS_REGION}:${ACCOUNT_ID}:${QUEUE_NAME}"
    }
  ]
}

*Replace ${AWS_REGION}, ${ACCOUNT_ID}, and ${QUEUE_NAME} with your values.*

EEFA warning – Do not grant *:* or sqs:* on * in production; limit the policy to the exact queue ARN.

---

3. Verifying Queue URL & Region Inside n8n

3.1. Confirm environment variables

Add the following lines to your .env or Docker‑Compose file exactly as shown:

QUEUE_MODE=aws-sqs
AWS_REGION=us-east-1
SQS_QUEUE_URL=https://sqs.us-east-1.amazonaws.com/123456789012/my-queue

3.2. Run the built‑in sanity check

docker exec -it n8n n8n queue:check

Expected output:

✔ Queue URL reachable
✔ IAM credentials valid
✔ Worker can receive a test message

If any check fails, note the AWS SDK error message for the next troubleshooting step.

---

4. Configuring a Production‑Ready IAM Role

4.1. Create the role (single CLI line)

aws iam create-role \
  --role-name n8nSqsWorker \
  --assume-role-policy-document file://trust-policy.json

4.2. Attach the policy from Section 2

aws iam put-role-policy \
  --role-name n8nSqsWorker \
  --policy-name n8nSqsAccess \
  --policy-document file://sqs-policy.json

4.3. (Optional) Restrict to a VPC endpoint

aws iam put-role-policy \
  --role-name n8nSqsWorker \
  --policy-name VpcEndpointAccess \
  --policy-document file://vpc-endpoint-policy.json

4.4. Assign the role to the compute resource

Console → Task Definition → IAM role = n8nSqsWorker.

4.5. Remove static credentials

Delete AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from .env. n8n will automatically use the instance profile.

EEFA tip – After role assignment, restart the worker and re‑run n8n queue:check. If you see AccessDenied, verify the role’s trust relationship allows ecs-tasks.amazonaws.com or ec2.amazonaws.com.

---

5. Manual Connectivity Test Using AWS CLI

These three short commands simulate the exact flow n8n performs.

1. List queues – confirms auth & region

   aws sqs list-queues --region $AWS_REGION
   

2. Send a test message

   aws sqs send-message \
     --queue-url $SQS_QUEUE_URL \
     --message-body '{"test":"n8n"}' \
     --region $AWS_REGION
   

3. Receive the test message

   aws sqs receive-message \
     --queue-url $SQS_QUEUE_URL \
     --max-number-of-messages 1 \
     --wait-time-seconds 5 \
     --region $AWS_REGION
   

If the receive command returns a message with a ReceiptHandle, the queue is functional. Delete the test message with:

aws sqs delete-message \
  --queue-url $SQS_QUEUE_URL \
  --receipt-handle <ReceiptHandle> \
  --region $AWS_REGION

---

6. Full‑Scope Troubleshooting Checklist

• Credentials – aws sts get-caller-identity returns the expected ARN.
• Region consistency – AWS_REGION matches the region segment of SQS_QUEUE_URL.
• Network – Security group allows outbound HTTPS (443) and, if using a VPC endpoint, inbound from that endpoint.
• IAM policy – Includes all actions from Section 2 and the ARN exactly matches the queue.
• Clock skew – date -u is within 5 minutes of AWS time (verify with aws s3api list-buckets).
• Queue type – For FIFO queues, ensure MessageGroupId is configured in the n8n SQS node.
• Dead‑Letter Queue – Verify the DLQ is not full; a saturated DLQ can cause empty receives.
• n8n logs – Search queueModeError in ~/.n8n/logs for stack traces.

---

7. Real‑World Edge Cases (EEFA)

Edge Case	Why it Happens	Production‑grade Fix
Cross‑account queue access	IAM user in Account A but queue lives in Account B	Add a resource‑based policy on the SQS queue granting arn:aws:iam::ACCOUNT_A:root the required actions.
VPC endpoint DNS mismatch	Private DNS disabled; worker resolves public endpoint, which is blocked	Enable *Private DNS* on the VPC endpoint **or** set AWS_ENDPOINT_URL to the endpoint URL.
FIFO queue without MessageGroupId	n8n sends messages lacking the required attribute	In the n8n SQS node, set **Message Group ID** (e.g., workflow ID) or switch to a standard queue.
Throttling (TooManyRequestsException)	Worker polls faster than the queue’s limit (max 20 req/s)	Add exponential back‑off via QUEUE_POLL_INTERVAL_MS in n8n config.
Payload > 256 KB	SQS payload limit exceeded	Store large data in S3 and send only the S3 object reference in the SQS message.

---

Conclusion

The most common n8n + AWS SQS integration failures stem from mismatched credentials, region settings, or network restrictions. By:

1. Applying the minimal, scoped IAM policy,
2. Ensuring environment variables precisely reflect the queue URL and region,
3. Verifying connectivity with the AWS CLI, and
4. Using a dedicated IAM role instead of static keys,

you create a production‑grade, secure pipeline where n8n workers reliably pull and push jobs. These steps eliminate “InvalidAccessKeyId”, “SignatureDoesNotMatch”, “QueueDoesNotExist”, and timeout errors, keeping your workflow automation robust in real‑world deployments.