EN

SignatureDoesNotMatch on a presigned S3 upload

A presigned PUT fails when the browser sends a header the signature did not cover, or a different content type. Read SignedHeaders from the URL, sign exactly what the browser will send, and check the object afterwards.

The server hands the browser a presigned URL, the browser PUTs the file, and S3 (or R2, or MinIO) answers 403 with:

<Error>
  <Code>SignatureDoesNotMatch</Code>
  <Message>The request signature we calculated does not match the signature you provided.</Message>
</Error>

Or worse, the browser console shows only a CORS error and no status at all, because the preflight never got a chance to succeed. Both symptoms usually have the same cause, and the error message is honest: the request that arrived is not the request that was signed.

What SigV4 actually signs

A presigned URL is a signature over a canonical description of the request: the HTTP method, the path, the query parameters, a declared list of headers, and a payload hash. The declared list is right there in the URL:

https://bucket.s3.eu-west-1.amazonaws.com/uploads/01JC.../photo.jpg
  ?X-Amz-Algorithm=AWS4-HMAC-SHA256
  &X-Amz-Credential=...
  &X-Amz-Date=20261113T101500Z
  &X-Amz-Expires=600
  &X-Amz-SignedHeaders=content-type%3Bhost
  &X-Amz-Signature=...

X-Amz-SignedHeaders=content-type;host is the contract. The request must carry those headers, with exactly those values. Anything missing, extra in that list, or spelled differently and the recomputed signature differs.

So the first debugging step is not to read your code — it is to decode X-Amz-SignedHeaders from the failing URL and compare it with what the request actually sends, in the browser's network tab.

The four things that usually differ

1. The browser set a content type you did not sign. This is the most common one. fetch(url, { method: 'PUT', body: file }) with no headers does not send no content type — the browser derives one from the File, and it will not always equal what your server signed. Sometimes it is application/octet-stream, sometimes it is the type with a charset appended. Always send the header explicitly, with the same string the server signed:

const { url, contentType } = await fetch('/api/uploads', {
  method: 'POST',
  body: JSON.stringify({ name: file.name, type: file.type, size: file.size }),
}).then((r) => r.json());

const res = await fetch(url, {
  method: 'PUT',
  headers: { 'content-type': contentType }, // the value the server signed, not file.type
  body: file,
});
if (!res.ok) throw new Error(`upload failed: ${res.status} ${await res.text()}`);

Returning the content type alongside the URL, instead of letting the client guess it twice, removes the whole class of mismatch.

2. You signed a header the browser is not allowed to set. content-length is a forbidden header name in fetch: the browser computes and sends it, but your code cannot set it, and some SDKs include it in SignedHeaders when you pass a length. If SignedHeaders contains anything other than content-type and host, ask yourself whether the browser can really produce it.

3. Something added an extra signed header. Checksum and integrity headers are the usual suspects: an SDK that adds one when it builds the presigned request will list it in SignedHeaders, and the browser will not send it. The check is the same — decode SignedHeaders, compare, and remove from the presigning call whatever the browser cannot reproduce.

4. The URL is simply expired, or the clocks disagree. X-Amz-Date plus X-Amz-Expires is an absolute window. A URL presigned at page load and used after the user picked a 200 MB file over a slow connection can expire mid-upload; a container with a drifted clock signs requests that are not valid yet. The error for an expired URL is usually AccessDenied / Request has expired rather than SignatureDoesNotMatch, which is itself a useful distinction.

Isolating CORS from signing

Browsers report a 403 with no CORS headers as a CORS error, which hides the real failure. Take the browser out of the loop and replay the exact request with curl:

curl -i -X PUT "$PRESIGNED_URL" \
  -H "content-type: image/jpeg" \
  --data-binary @photo.jpg
  • curl succeeds, browser fails → it is CORS, or a header the browser adds.
  • curl fails too → it is the signature, and the response body names the reason.

The bucket needs a CORS rule that allows the method, your origin and the content-type request header:

[{
  "AllowedOrigins": ["https://app.example.com", "http://localhost:3000"],
  "AllowedMethods": ["PUT", "GET"],
  "AllowedHeaders": ["content-type"],
  "ExposeHeaders": ["etag"],
  "MaxAgeSeconds": 3600
}]

ExposeHeaders: ["etag"] is only needed if you read the ETag from the response in JavaScript — without it the header is invisible to your code even though it arrived.

Presigning on the server

// app/api/uploads/route.ts
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { ulid } from 'ulid';

const s3 = new S3Client({
  region: process.env.STORAGE_REGION ?? 'auto',
  endpoint: process.env.STORAGE_ENDPOINT, // R2: https://<account>.r2.cloudflarestorage.com
  credentials: {
    accessKeyId: process.env.STORAGE_ACCESS_KEY_ID!,
    secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY!,
  },
});

const ALLOWED = new Set(['image/jpeg', 'image/png', 'image/webp']);
const MAX_BYTES = 10_000_000;

export async function POST(req: Request) {
  const user = await requireUser(req);
  const { name, type, size } = await req.json();

  if (!ALLOWED.has(type)) return new Response('unsupported type', { status: 415 });
  if (!Number.isInteger(size) || size <= 0 || size > MAX_BYTES) {
    return new Response('too large', { status: 413 });
  }

  // The server owns the key. Never the user's filename.
  const ext = { 'image/jpeg': 'jpg', 'image/png': 'png', 'image/webp': 'webp' }[type as string];
  const key = `uploads/pending/${user.id}/${ulid()}.${ext}`;

  const url = await getSignedUrl(
    s3,
    new PutObjectCommand({ Bucket: process.env.STORAGE_BUCKET!, Key: key, ContentType: type }),
    { expiresIn: 600 },
  );

  return Response.json({ url, key, contentType: type });
}

Two decisions in there are worth stating out loud.

The key is generated server-side. Using name from the request lets a client write ../../avatars/someone-else.jpg, or simply overwrite another user's object by guessing their key. Generate an opaque id and store the key in your table next to the row that owns it — store the key, not the URL, because URLs change the day you put a CDN in front of the bucket.

The size check in that handler is advisory. The client said 10 KB; nothing stops it from uploading 2 GB to a URL signed without a length constraint. If you need a hard cap, either use a presigned POST policy, which supports a content-length-range condition the storage service itself enforces, or treat the upload as untrusted until the server has confirmed it:

import { HeadObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';

const head = await s3.send(new HeadObjectCommand({ Bucket, Key: key }));
if ((head.ContentLength ?? 0) > MAX_BYTES) {
  await s3.send(new DeleteObjectCommand({ Bucket, Key: key }));
  throw new Error('upload exceeded the limit');
}

That confirmation step is also where you stop trusting the content type. The client declared image/png; only the bytes can prove it. Sniff the magic number server-side before you move the object from uploads/pending/ to the key you will serve publicly, and keep everything private by default — serve private objects with a short-lived presigned GET issued after an authorization check, not by making the bucket public.

If you would rather not maintain this

@core/storage is one StorageProvider interface over S3-compatible buckets — R2, S3, MinIO, B2 — signed with SigV4 through aws4fetch, so the same code runs on Node and on Cloudflare Workers. It presigns uploads with the content type and size signed, generates safe keys (generateKey, assertSafeKey), and ships local and memory drivers so uploads work in development and in tests without a bucket.

genpm add @core/storage

It installs into src/lib/storage in your repo, with adapters for Hono and Next.js. Without the CLI installed: npx -y @genpm-net/cli add @core/storage.