What S3's SignatureDoesNotMatch error means, how to compare the canonical request S3 computed with yours, and the usual causes: bad secret keys, presigned URL header mismatches, proxies, key encoding and the newer SDK checksum defaults.

S3 rejects a request with SignatureDoesNotMatch when the Signature Version 4 signature it computes differs from the one you sent, and the message, "The request signature we calculated does not match the signature you provided", gives no hint about which part differed. It is not a permissions error, so changing IAM policies never fixes it.
Something changed between signing and sending, or the signing key was wrong, and the error body says which.
The XML error response includes the StringToSign and CanonicalRequest that S3 computed. Turn on signing debug output in your client and compare the two canonical requests line by line. In Python, the botocore signer logs its version:
import logging
import boto3
from botocore.exceptions import ClientError
boto3.set_stream_logger("botocore.auth", logging.DEBUG) # logs CanonicalRequest and StringToSign
s3 = boto3.client("s3", region_name="eu-west-1")
try:
s3.put_object(Bucket="acme-uploads", Key="reports/q3 summary.pdf", Body=b"%PDF-1.7")
except ClientError as err:
error = err.response["Error"]
if error["Code"] == "SignatureDoesNotMatch":
print("S3 canonical request:\n", error.get("CanonicalRequest"))
print("S3 string to sign:\n", error.get("StringToSign"))
raise
The canonical request has the method, the encoded path, the sorted query string, the signed headers with their values and the payload hash. The first line that differs is the cause: a header value, a path encoding such as %20 versus +, or a header S3 received that was signed with a different value. The Signature Version 4 docs describe each part.
When every request fails, including a simple ListBuckets, the key is the suspect. A secret access key copied into a .env file or a Kubernetes secret with a trailing newline produces a valid-looking signature from the wrong key, and S3 answers SignatureDoesNotMatch rather than an unknown-key error, because the access key ID itself is fine. aws sts get-caller-identity with the same credentials confirms it quickly, and the longer-term fix is to drop static keys for a role on the compute that runs the code.
A presigned URL embeds a signature over the method, path, query parameters and a list of signed headers. If the URL was generated with ContentType="application/pdf", the upload must send exactly Content-Type: application/pdf, and a browser that sends application/octet-stream or adds ; charset=utf-8 breaks it. Metadata passed at signing time becomes x-amz-meta-* headers the client must also send.
In January 2025 the AWS SDKs started to calculate integrity checksums by default, from boto3 1.36 and JavaScript v3.729 onward. Some presigned upload code and many S3-compatible services fail with the extra checksum headers or parameters, and setting request_checksum_calculation to when_required in the client config, or AWS_REQUEST_CHECKSUM_CALCULATION=when_required in the environment, restores the old behavior.
A request signed for acme-uploads.s3.eu-west-1.amazonaws.com but sent through a proxy that changes the Host, strips headers or re-encodes the path will never match. Sign for the host the request finally reaches, and if a CDN sits in front, configure it to forward the headers that are part of the signature. For object keys with spaces, +, # or non-ASCII characters, hand-built URLs are the usual culprit, and letting the SDK build the request or presigned URL encodes them the way S3 expects. The S3 object key naming guidelines list the characters that need special handling.
Encore brings infrastructure from code, and a bucket declared in TypeScript creates signed upload and download URLs itself, so there is no access key, Region, checksum setting or signing code in the app to get out of sync.

Run in your terminal to get started locally.
// uploads/uploads.ts
import { api } from "encore.dev/api";
import { Bucket } from "encore.dev/storage/objects";
import { randomUUID } from "node:crypto";
// S3 on AWS, Cloud Storage on GCP, local storage under `encore run`.
export const attachments = new Bucket("attachments", { versioned: false });
interface UploadURL {
key: string;
url: string;
}
// The browser PUTs the file to the returned URL.
export const createUploadUrl = api(
{ expose: true, method: "POST", path: "/attachments/upload-url" },
async (): Promise<UploadURL> => {
const key = `${randomUUID()}.pdf`;
const { url } = await attachments.signedUploadUrl(key, { ttl: 300 });
return { key, url };
},
);
export const downloadUrl = api(
{ expose: true, method: "GET", path: "/attachments/:key/url" },
async ({ key }: { key: string }): Promise<{ url: string }> => {
const { url } = await attachments.signedDownloadUrl(key, { ttl: 900 });
return { url };
},
);
With an encore.service.ts file in uploads/, encore run serves the bucket locally, so the upload and download flow can be tested end to end on a laptop before any AWS account is involved. On deploy to your own AWS account, Encore creates the S3 bucket and signs the URLs for it, and Encore provisions an IAM role for the service, as the AWS infrastructure docs describe.
Signing bugs usually appear only against Amazon S3, which makes them slow to debug for anyone, coding agents included. With the bucket and its URLs in the same file, an agent that adds an upload endpoint can exercise the whole flow locally in the same change.
Best fit: Apps that hand out upload and download links for files in their own AWS account and want the signing done by the platform rather than by code they maintain.
S3 recomputed the Signature Version 4 signature from the request it received and got a different value than the one you sent. Either the secret key used to sign was wrong, or the request changed between signing and arrival, such as a different header, method, path or query string.
The browser request does not match what was signed. The most common cause is a Content-Type header that differs from the ContentType used when generating the URL, or headers the SDK added to the signature, such as checksum or metadata headers, that the browser does not send.
The XML error body includes StringToSign and CanonicalRequest as S3 computed them. Enable debug logging in your SDK, for example the botocore.auth logger in boto3, and compare the canonical request line by line to find the header or encoding that differs.
Yes. A secret key with a trailing newline or space, often from a file or environment variable, signs correctly on your side but differs from the correct key, so S3 reports SignatureDoesNotMatch instead of an unknown key error. With Encore, a declared bucket's signedUploadUrl and signedDownloadUrl create presigned URLs without any key or signing code in the app.
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.