Nov 20, 20265 min read

Fix S3 SignatureDoesNotMatch Errors

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.

Illustration for Fix S3 SignatureDoesNotMatch Errors

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.

SignatureDoesNotMatch causes at a glance

SituationLikely causeFix
Every request failsSecret key has whitespace or is wrongTrim and re-copy the key, or use a role
Presigned PUT from a browserContent-Type differs from the signed oneSend exactly the signed header
Works locally, fails behind a proxyProxy or CDN rewrites headers or the pathSign the request the proxy forwards, or bypass it
Keys with spaces, + or UnicodeDouble or missing URL encodingLet the SDK build the URL
S3-compatible store or old presign codeSDK checksum headers added by defaultSet checksum calculation to when_required
Error is RequestTimeTooSkewed insteadClock off by more than 15 minutesSync the clock

How do you see what S3 expected?

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.

Is the secret key wrong?

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.

Why do presigned URLs fail?

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.

What about proxies and key encoding?

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.

How does Encore handle signed URLs?

Encore

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.

Application code passes through Encore and infrastructure guardrails to resources provisioned in your own AWS or GCP account.
Encore provisions the infrastructure your application needs in your own AWS or GCP account.
Get started
brew install encoredev/tap/encore &&
encore app create
Copy

Run in your terminal to get started locally.

~
$ encore app create docs-app --example=ts/hello-world$ cd docs-app && mkdir uploads
// 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.

Frequently asked questions

What does SignatureDoesNotMatch mean in S3?

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.

Why does my presigned URL upload fail with SignatureDoesNotMatch?

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.

How do I see what S3 expected?

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.

Can a wrong secret access key cause SignatureDoesNotMatch?

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.

~/orders — claude
Claude Code
Claude Code v2.1.180Opus 5.5~/orders