Introduction

When you upload a file to S3, the object metadata includes a Content-Type. If that type is wrong, browsers and downstream clients may handle the file incorrectly. With the AWS CLI, the usual fix is to set --content-type explicitly during upload or copy instead of relying on automatic inference.

Set the Content Type on Upload

For a local file upload, use aws s3 cp with --content-type:

aws s3 cp styles.css s3://my-bucket/assets/styles.css \
  --content-type text/css

This tells S3 to store the object with the desired metadata. The same pattern works for HTML, JSON, JavaScript, images, and other object types.

Why This Matters

S3 stores bytes plus metadata. If the content type is wrong, a browser may download the file instead of rendering it, or a client may parse it incorrectly.

For example:

• 'text/html for HTML pages'
• 'text/css for stylesheets'
• 'application/javascript for JavaScript'
• 'application/json for JSON payloads'

Getting this right at upload time is much easier than correcting it later.

Copying Existing S3 Objects Is Different

If you are copying an object inside S3 and want to change its metadata, you need the copy operation to replace metadata rather than preserve the original object metadata.

That is why metadata updates are often done with an S3 copy command that explicitly replaces metadata. The important concept is:

• plain copy keeps the old metadata
• metadata replacement applies the new Content-Type

When people think they “copied with the right content type” but the object still serves the old type, metadata preservation is usually the reason.

Prefer Explicit Metadata for Important Assets

For files that browsers consume directly, do not rely entirely on guessing. Setting --content-type explicitly makes deployment more predictable and easier to review.

This is especially useful in build pipelines where the output file extension may not be enough or where a wrong inferred type would cause visible runtime problems.

Verify the Result

After upload, inspect the object metadata:

aws s3api head-object --bucket my-bucket --key assets/styles.css

Check that ContentType matches what you intended. This is the fastest way to confirm that the upload command actually produced the correct metadata.

Deployment Automation Should Encode the Type

If the same asset type is uploaded repeatedly, put the --content-type rule into the deployment command or script itself. That prevents drift between manual uploads and automated releases.

Common Pitfalls

• Assuming S3 will always infer the correct type automatically.
• Uploading browser assets without setting --content-type explicitly.
• Copying objects within S3 and forgetting that metadata may be preserved unless explicitly replaced.
• Verifying that the file exists in the bucket but not verifying its metadata.
• Fixing content type manually in the console instead of making the CLI command deterministic.

Metadata Fixes Should Be Repeatable

If content type problems happened once, they will likely happen again unless the deployment path is made deterministic. Treat the metadata rule as part of the artifact release process, not as a one-time manual correction.

Summary

• Use aws s3 cp ... --content-type ... to upload with the correct content type.
• Wrong content type metadata can break browser or client behavior even when the file bytes are correct.
• Copying existing S3 objects may preserve old metadata unless you explicitly replace it.
• Verify the stored metadata with aws s3api head-object.
• Prefer explicit content-type settings for important deployed assets.