Step by Step Guide to solve n8n S3 Upload Error
Who this is for: n8n developers and ops engineers who need reliable S3 uploads in production workflows. We cover this in detail in the n8n API Integration Errors Guide.
Quick Fix: The most common failure points are IAM permissions or bucket‑policy mismatches.
- Verify the Access Key / Secret in the AWS Credentials resource.
- Ensure the IAM user/role has
s3:PutObject,s3:AbortMultipartUpload, ands3:ListBucket. - Confirm the bucket policy allows the same actions for the principal.
- Match the node’s Region with the bucket’s region.
Update the policy, re‑run the node, and the upload should succeed.
Quick Reference: AWS SDK Error Messages
| AWS SDK Message | Typical Meaning |
|---|---|
AccessDenied: Access Denied |
IAM user/role lacks required S3 actions or bucket policy blocks it |
NoSuchBucket: The specified bucket does not exist |
Bucket name typo or wrong region |
InvalidSignatureException |
Wrong credentials or mismatched region |
EntityTooLarge |
Object > 5 GB without multipart upload enabled |
NetworkError |
VPC endpoint or outbound internet blocked |
These messages guide the systematic diagnosis that follows.
Common Root Causes
| Category | Typical Trigger |
|---|---|
| IAM Permissions | Missing s3:PutObject, s3:AbortMultipartUpload, s3:ListBucket |
| Bucket Policy | Explicit Deny or missing Allow for the principal |
| Region Mismatch | Node set to a different region than the bucket |
| Credentials | Stale/rotated keys or missing session token for assumed role |
| Object Size / Multipart | File > 5 GB without multipart enabled |
| Network / VPC | No internet egress or missing VPC endpoint for S3 |
Step‑by‑Step Diagnosis in n8n
1. Log the payload before the upload
// Function node – log key & size
console.log('Key:', item.json.key);
console.log('Size (bytes):', Buffer.byteLength(item.json.data, 'utf8'));
// Return the original item unchanged return items;
2. Test credentials with a List operation
Add a S3 List node pointing at the same bucket.
*If it fails, the issue is credentials or IAM.*
3. Capture the raw error
In the S3 Upload node:
• Turn “Continue on Fail” off.
• Set “Raw Response” to true.
Run the workflow in **Execute Workflow** mode and copy the full error object (error.code, error.message).
Fixing Permission Errors
IAM Policy (JSON) – Part 1
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
IAM Policy – Part 2
"Action": [
"s3:PutObject",
"s3:AbortMultipartUpload",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::my-target-bucket",
"arn:aws:s3:::my-target-bucket/*"
]
}
]
}
EEFA Note – Scope Resource to the exact bucket/prefix you need; avoid a wildcard on the bucket name.
Bucket Policy (JSON) – Part 1
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowN8nUploads",
"Effect": "Allow",
Bucket Policy – Part 2
"Principal": { "AWS": "arn:aws:iam::123456789012:user/n8n-uploader" },
"Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
"Resource": "arn:aws:s3:::my-target-bucket/*"
}
]
}
Quick Permission Checklist
- [ ] IAM principal has
s3:PutObjecton the bucket ARN. - [ ] IAM principal has
s3:ListBucketon the bucket (required for pre‑flight). - [ ] No explicit
Denystatements in the bucket policy. - [ ] If using AssumeRole, the trust policy permits n8n’s role to assume it.
Fixing Bucket‑Configuration Errors
| Issue | Fix |
|---|---|
| Wrong region | Set the node’s Region to the bucket’s region (see bucket Properties). |
| CORS needed for presigned URLs | Add a CORS rule that allows PUT from your n8n host. |
| Versioning enabled | Include the VersionId in the node’s **Object Key** when overwriting a specific version. |
| Public access block | Verify that the bucket’s **Block Public Access** settings don’t unintentionally block your IAM principal. |
Advanced: Custom Upload with a Function Node
1. Load the SDK & configure credentials
const AWS = require('aws-sdk');
const credentials = $node["AWS Credentials"].json; // resource name
AWS.config.update({
accessKeyId: credentials.accessKeyId,
secretAccessKey: credentials.secretAccessKey,
region: "eu-west-2"
});
2. Create the S3 client
const s3 = new AWS.S3();
3. Define upload parameters
const params = {
Bucket: "my-target-bucket",
Key: item.json.key, // e.g. "uploads/report.pdf"
Body: Buffer.from(item.json.data, "utf-8"),
ServerSideEncryption: "AES256", // optional
Metadata: { source: "n8n-workflow" }
};
4. Perform the upload and handle the promise
return s3.upload(params).promise()
.then(data => {
console.log('Upload success:', data);
return [{ json: { success: true, location: data.Location } }];
})
.catch(err => {
console.error('Upload error:', err);
throw err; // surfaces as node error
});
EEFA Warning – The Function node runs in the same process as n8n. For high‑throughput pipelines, prefer the native S3 Upload node (it streams data and respects concurrency limits).
Pre‑Run Checklist
| Item | Why It Matters |
|---|---|
| Credentials are up‑to‑date | Prevents InvalidSignatureException. |
IAM policy includes PutObject |
Avoids AccessDenied. |
| Bucket policy allows the IAM principal | Prevents hidden denies. |
| Region matches bucket | Stops InvalidEndpoint errors. |
| Object size ≤ 5 GB or multipart enabled | Avoids EntityTooLarge. |
Network egress to s3.<region>.amazonaws.com |
Prevents NetworkError. |
Next Steps
- Automated Retry Logic – add a Retry node or enable “Retry on Fail” to recover from transient S3 throttling.
- Monitoring & Alerts – pipe errors to Slack or Microsoft Teams for real‑time ops notifications.
- Security Hardening – rotate IAM keys regularly and enable MFA Delete on the bucket for extra protection.
Conclusion
S3 upload failures in n8n boil down to three production‑grade checks: correct credentials, proper IAM + bucket permissions, and region‑aligned configuration. By validating each checklist item, inspecting the raw AWS error, and, when needed, using a custom SDK snippet, you can quickly restore reliable uploads. The same disciplined approach applies to any n8n connector that relies on AWS services, ensuring stable, secure data pipelines in real‑world production.
