Upload file content type charset is dropped

[jimmystlr]

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

When uploading text files to Supabase Storage using the Python SDK with a
Content-Type that includes a charset parameter (for example
text/markdown; charset=UTF-8), the charset information is silently dropped
during the upload process.

Although the upload request explicitly includes the full Content-Type
(including charset), after the upload completes:

• The file metadata returned by the Storage info / list API
• The HTTP response headers returned by public URLs or signed URLs

only contain the base MIME type (e.g. text/markdown) and never include the
charset parameter.

This leads to incorrect or ambiguous character encoding handling in browsers and
HTTP clients that rely on response headers for charset detection.

---

To Reproduce

1. Upload a file with charset specified

from supabase import create_client

supabase = create_client(SUPABASE_URL, SUPABASE_KEY)

with open("example.md", "rb") as f:
    supabase.storage.from_("test-bucket").upload(
        "example.md",
        f,
        file_options={
            "content-type": "text/markdown; charset=UTF-8"
        }
    )

2. Verify upload request

• The actual HTTP request sent by the Python SDK is multipart/form-data
• The file part includes:

Content-Type: text/markdown; charset=UTF-8

---

3. Query file metadata

files = supabase.storage.from_("test-bucket").list()

Returned metadata shows:

contentType: "text/markdown"

❌ charset=UTF-8 is missing.

---

4. Access via signed URL or public URL

url = supabase.storage.from_("test-bucket").create_signed_url(
    "example.md", 60
)["signedURL"]

curl -I "<signed-url>"

Response header:

Content-Type: text/markdown

❌ charset=UTF-8 is missing.

---

Expected behavior

If a file is uploaded with:

Content-Type: text/markdown; charset=UTF-8

Supabase Storage should either:

1. Preserve the full Content-Type (including charset) in stored metadata and
   HTTP responses
   or
2. Clearly document that MIME parameters (such as charset) are intentionally
   stripped and unsupported

---

Root cause analysis (from backend code inspection)

After inspecting the Supabase Storage backend source code, the root cause is in
src/storage/backend/s3/adapter.ts, specifically the uploadObject method:

The Problem

1. Content-Type is correctly extracted: During multipart uploads, the backend
   correctly extracts the full Content-Type (including charset) from
   formData.fields.contentType?.value in fileUploadFromRequest
   (src/storage/uploader.ts:344).

2. Content-Type is correctly sent to S3: The full Content-Type (including
   charset) is passed to S3's Upload command as the ContentType parameter
   (src/storage/backend/s3/adapter.ts:152).

3. Charset is lost when retrieving metadata: After upload completes, for
   non-zero-byte files, the code calls headObject to retrieve metadata
   (src/storage/backend/s3/adapter.ts:175). S3's HeadObjectCommand returns a
   ContentType that has been normalized/stripped of the charset parameter.

4. Normalized value overwrites original: The code uses the mimetype from
   headObject response (src/storage/backend/s3/adapter.ts:190) instead of the
   original contentType parameter, causing the charset to be lost.

Code Evidence

// src/storage/backend/s3/adapter.ts:174-190
const metadata = hasUploadedBytes
  ? await this.headObject(bucketName, key, version)
  : {
      mimetype: contentType,
      // ...
    }

return {
  // ...
  mimetype: metadata.mimetype,
  // ...
}

Why Zero-Byte Files Work

For zero-byte files, the code bypasses headObject and directly uses the
original contentType parameter (line 179), which is why charset is
preserved for empty files but not for files with content.

The Fix

The code should use the original contentType parameter for non-zero-byte
files instead of relying on headObject's normalized response, or merge the
original contentType with other metadata from headObject.

---

Why this is a bug (not a feature request)

• charset is a standard, semantically significant part of Content-Type
• Browsers and HTTP clients rely on it for correct text decoding
• The Python SDK explicitly sends the full Content-Type
• Supabase Storage silently drops it without documentation or warning

---

System information

• OS: macOS / Linux
• SDK: supabase==2.27.0, storage3==2.27.0
• Python version: 3.12
• Storage: Supabase managed Storage

[abdulshaikh-ht]

In my case, the Supabase UI displays charset=utf-8 for the file, but when I fetch or open it in the browser, the charset portion is omitted in the headers.

xhtml-supabase-issue.mov

[SushanthMusham]

Hey @ferhatelmas and @fenos! I see that this was given out a few months ago. I have some free time this weekend and would love to try to fix this S3 charset bug if no one else is working on it right now. Please tell me if it's okay for me to take it over!

[ferhatelmas]

@SushanthMusham yes, feel free to prepare a fix. I can help to review and get it in.

[SushanthMusham]

Hi @ferhatelmas,

Sorry for the late reply! Thank you for letting me work on this.

I will work on the fix and open a PR in a couple of days.

Thanks!

[SushanthMusham]

Hey @ferhatelmas, I've raised the PR for this fix!
The root cause was in bufferedMultipartUpload where headObject response was being used for mimetype, which strips the charset. Fixed it by using the original contentType parameter directly instead of relying on S3's normalized response.
Would love your feedback on it!

[SushanthMusham]

Hey @ferhatelmas, just a gentle ping on PR #975 whenever you get a chance! No rush 🙂