uploadToSignedUrl() option { upsert: true } not working

[kjhughes]

Bug report

• I confirm this is a bug with Supabase, not with my own application.
• I confirm I have searched the Docs, GitHub Discussions, and Discord.

Describe the bug

Calling uploadToSignedUrl() with { upsert: true } is failing to honor the upsert: true option.

To Reproduce

Steps to reproduce the behavior, please provide code snippets or a repository:

Code

const { data: signedUrlData, error: signedUrlError } = await supabase
  .storage
  .from('auth-only')
  .createSignedUploadUrl('private/secret.js')
if (signedUrlError) {
  console.error(signedUrlError)
} else if (signedUrlData !== null) {
  const token = signedUrlData.token
  const fileBody = fs.readFileSync('dist/protected/secret.js')
  const { data: uploadData, error: uploadError } = await supabase
    .storage
    .from('auth-only')
    .uploadToSignedUrl('private/secret.js', token, fileBody, {upsert: true, contentType: 'text/javascript'})
  if (uploadError) {
    console.error(uploadError)
  } else {
    console.log(uploadData)
  }
}

Expected behavior

I expect theprivate/secret.js storage object to be replaced.

Instead, the following error occurs:

StorageApiError: The resource already exists
    at <anonymous> (/Users/kjh/proj/entel-common.com/node_modules/@supabase/storage-js/dist/main/lib/fetch.js:22:20)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5) {
  __isStorageError: true,
  status: 400
}

Note that replacing the code based on uploadToSignedUrl() with the below code based on update() does work:

const fileBody = fs.readFileSync('dist/protected/secret.js')
const { error } = await supabase
  .storage
  .from('auth-only')
  .update('private/secret.js', fileBody, { upsert: true, contentType: 'text/javascript'})
if (error)
  console.error(`Error:`, error)

System information

• OS: macOS Ventura 13.6
• Browser: chrome
• Version of supabase-js: 2.36.0
• Version of Node.js: 20.5.0

See Also

Similar unresolved past report in Discord: Problem with createSignedUploadUrl

[denbondd]

Same for me, did anyone find a workaround? I'm currently deleting a file before generating a signed URL

[MilesV64]

+1

[alberto-abarzua]

Same here! I don't want to have to delete the file before upload. :(

[mandarini]

Thanks for reporting this! This is actually working as designed, not a bug. Let me explain why and how to fix it.

The Problem

The upsert option passed to uploadToSignedUrl() has no effect. The upsert behavior is determined when the signed URL is created, not when uploading to it.

Why This Happens

When you call createSignedUploadUrl(), the server generates a JWT token that encodes the upload permissions, including whether upsert is allowed:

// Decoded JWT token from a signed URL
  {
    "url": "bucket/path/to/file.js",
    "upsert": false,  // <-- This is baked into the token at creation time
    "iat": 1696600000,
    "exp": 1696607200
  }

During upload, the Storage API backend extracts the upsert setting from the JWT token, not from request headers:

// Storage API backend code
  const { owner, upsert } = await request.storage
    .from(bucketName)
    .verifyObjectSignature(token, objectName)  // upsert comes from JWT

  await request.storage.asSuperUser().from(bucketName).uploadFromRequest(request, {
    isUpsert: upsert,  // Uses the JWT value, ignores any headers
  })

This is a security feature. Signed URLs grant pre-defined, limited permissions to untrusted clients. If the upsert flag could be overridden during upload, it would defeat the purpose of the signed URL's permission model.

The Fix

Pass { upsert: true } when creating the signed URL, not when uploading:

  // Don't do this - upsert here is ignored
  const { data } = await supabase.storage
    .from('bucket')
    .createSignedUploadUrl('private/secret.js')

  await supabase.storage
    .from('bucket')
    .uploadToSignedUrl(data.path, data.token, fileBody, { upsert: true })  // This has no effect!


  // Do this - upsert at URL creation time
  const { data } = await supabase.storage
    .from('bucket')
    .createSignedUploadUrl('private/secret.js', { upsert: true })  // <-- HERE

  await supabase.storage
    .from('bucket')
    .uploadToSignedUrl(data.path, data.token, fileBody)  // No upsert needed here

Why update() Works

Your workaround using update() works because that method directly calls the storage API with your credentials (not a signed URL), so the upsert header is respected. With signed URLs, the permissions are pre-encoded in the token.

Test Confirmation

We have a test case that confirms this behavior works correctly when used properly:

  // From packages/core/storage-js/test/storageFileApi.test.ts:283-301
  test('can upload overwriting files with a signed url', async () => {
    // First upload a file
    await storage.from(bucketName).upload(uploadPath, file)

    // Create signed URL WITH upsert: true
    const { data } = await storage.from(bucketName).createSignedUploadUrl(uploadPath, {
      upsert: true,  // Upsert specified at creation time
    })

    // Upload again - succeeds because upsert was enabled at creation
    const uploadRes = await storage
      .from(bucketName)
      .uploadToSignedUrl(data.path, data.token, file)

    expect(uploadRes.error).toBeNull()  // Success!
  })

What could we do to improve the experience

I agree this behavior isn't obvious. We should probably:

1. Update the uploadToSignedUrl() JSDoc to clarify that upsert in FileOptions has no effect for signed URL uploads
2. Add a note explaining that upsert permission is determined at URL creation time

So I will close this issue since:

• Not a bug - this is the intended security model for signed URLs
• Fix: Pass { upsert: true } to createSignedUploadUrl(), not uploadToSignedUrl()

The reason why your workaround works: update() uses direct API calls, not signed URLs.

Let me know if you have any questions!

And once again thank you for contributing to Supabase! 💚