MIME Types for HTML, CSS, JS, JSON, and SVG: The Developer Reference

Overview

This guide gives you a practical reference for the MIME types developers most often need when serving front-end assets and API responses. If you have ever seen errors like “Refused to apply style,” “Failed to load module script,” or a browser rendering raw text instead of the expected asset, the cause is often a mismatch between the file and its declared content type.

At a high level, a MIME type tells the client what kind of content is being sent. On the web, this usually appears in the HTTP response header:

Content-Type: text/html; charset=utf-8

Browsers use that header to decide how to interpret the response. Static hosts, web servers, object storage layers, reverse proxies, and CDNs may all influence the final value. That is why MIME type problems often show up only after deployment, even when everything worked in local development.

For quick reference, here are the common types covered in this article:

If you are troubleshooting a hosted page, it also helps to confirm that your platform is serving the file itself rather than a fallback HTML page. A missing CSS or JS file often returns an HTML error document with text/html, which then triggers a MIME type error in the browser.

Core concepts

This section explains what MIME types do, why they matter, and how the most common asset types should be served.

What a MIME type actually is

MIME originally came from email systems, but on the web it has become the standard way to label content. In HTTP, the browser reads the Content-Type response header and decides how to process the payload. A few examples:

• text/html tells the browser to parse the response as HTML.
• text/css tells the browser to treat the file as a stylesheet.
• application/json signals structured JSON data, usually for APIs or machine-readable responses.
• image/svg+xml identifies an SVG image.

When the header is missing, incorrect, or overwritten by a proxy or host, browsers may guess incorrectly or refuse to process the asset. Modern browsers are stricter than older ones, especially for scripts and stylesheets.

Reference: MIME type for HTML

The standard choice for HTML is:

Content-Type: text/html; charset=utf-8

This is the right answer for normal web pages, preview pages, single-file demos, error documents, and most static landing pages. The charset=utf-8 portion helps ensure text renders correctly across environments.

Common HTML-related mistakes include:

• Serving HTML as text/plain, which makes the browser display markup instead of rendering it.
• Returning HTML for a missing asset path, causing a CSS or JS request to receive text/html.
• Using file download headers unintentionally, which can cause a page to download instead of open.

Reference: MIME type for CSS

CSS should be served as:

Content-Type: text/css; charset=utf-8

This matters more than many developers expect. Browsers often reject stylesheets with the wrong MIME type, particularly when the response is actually an HTML error page. A classic console error says the stylesheet was not loaded because its MIME type was text/html instead of text/css.

If your CSS fails in production, check these items in order:

1. Does the URL point to a real file?
2. Is the host returning a 404 page or route fallback as HTML?
3. Did the upload or object storage metadata assign the wrong content type?
4. Is a CDN caching an outdated header?

Reference: MIME type for JavaScript

JavaScript is commonly served as:

Content-Type: text/javascript; charset=utf-8

In practice, JavaScript content type handling has some history behind it, and you may still encounter older values in legacy systems. For current projects, use a modern, consistent configuration and verify that your host serves both classic scripts and module scripts correctly.

This is especially important for ES modules:

<script type="module" src="/app.js"></script>

Module loading tends to be strict. If the server sends back HTML or another wrong type, browsers are less forgiving than they once were. A path typo, SPA rewrite rule, or misconfigured static host can turn a valid script request into a MIME type error quickly.

Reference: MIME type for JSON

JSON should usually be served as:

Content-Type: application/json; charset=utf-8

This is common for APIs, config endpoints, search indexes, manifests, exported data, and webhook responses. If JSON is sent as text/plain or text/html, consumers may still parse it in some contexts, but the behavior becomes less predictable and tooling may not handle it cleanly.

Typical JSON problems include:

• An API gateway returning an HTML error page instead of JSON.
• A server-side exception handler rewriting all failures to text/html.
• Static config files uploaded with generic binary metadata.

When an API is expected to return JSON, check both the response body and the headers. Many developers inspect only the body and miss the fact that a proxy changed the Content-Type.

Reference: MIME type for SVG

SVG should be served as:

Content-Type: image/svg+xml

SVG is an image format, but because it is XML-based, it behaves differently from bitmap images in some workflows. It may be used in <img> tags, CSS backgrounds, inline markup, icon systems, or downloadable assets. If served with the wrong type, browsers may not render it properly, may trigger downloads, or may handle it inconsistently across contexts.

With SVG, also pay attention to:

• Whether the file is embedded inline or requested as a separate asset.
• Whether a security policy or sanitizer is stripping markup.
• Whether compression, CDN transforms, or image pipelines alter the file headers.

Why wrong MIME type errors happen

Most MIME type problems come from one of a few repeatable patterns:

• Extension mapping is missing: the server does not know what type to assign to a file extension.
• Fallback routing is too aggressive: unknown paths return your main HTML file, even for CSS and JS requests.
• Object storage metadata is wrong: uploaded files keep default or generic content types.
• CDN cache is stale: headers were fixed at origin, but edge nodes still serve old metadata.
• Reverse proxy overrides: a proxy adds or rewrites headers unexpectedly.
• Error pages hide the real issue: the browser reports a MIME mismatch, but the underlying problem is actually a 403 or 404.

That last case is common enough to remember: a wrong MIME type error often means “you did not get the file you thought you requested.”

Related terms

To troubleshoot content type issues well, it helps to separate several closely related concepts that are often mixed together.

Content-Type vs MIME type

In day-to-day web development, these terms are usually used interchangeably. Strictly speaking, the MIME type is the value, and Content-Type is the HTTP header that carries it.

Media type

You may also see the term “media type.” In modern HTTP documentation, “media type” is often the broader or preferred term, but in practical debugging conversations developers still say MIME type. Both point to the same family of identifiers such as text/html or application/json.

Charset

The charset declares the text encoding, commonly UTF-8. It appears as a parameter on text-based content types:

text/html; charset=utf-8

It does not replace the MIME type; it adds detail to it.

Accept header

The request-side Accept header tells the server what response formats the client can handle. This is different from the response-side Content-Type. For example, a client may send:

Accept: application/json

and expect the server to respond with:

Content-Type: application/json

Content-Disposition

This header controls whether a response is displayed inline or treated as a download. A perfectly correct MIME type can still appear to “misbehave” if Content-Disposition forces attachment download behavior.

Content-Encoding

This header indicates compression such as gzip or br. It is independent of MIME type. A file can be text/css and also be gzip-compressed.

Sniffing

Some browsers historically guessed content types when headers were absent or wrong. Modern security practices reduce reliance on sniffing. In other words, you should not expect browsers to rescue an incorrectly configured asset pipeline.

Practical use cases

Here is how this reference applies in real development and hosting workflows.

1. Static hosting for a single HTML page or demo

When you upload a simple project with index.html, styles.css, app.js, and an icon.svg, all four files need correct content types. If only HTML is configured properly, the page may load but appear unstyled or non-interactive.

A simple verification checklist:

1. Open DevTools and reload the page.
2. Inspect the Network tab.
3. Click each asset request.
4. Confirm the status code is what you expect.
5. Confirm the Content-Type matches the file type.

If your static site seems partly broken, compare the requested URL, returned body, and returned content type side by side. That usually exposes the issue faster than reading console errors alone.

For broader deployment debugging, see HTML File Not Loading Correctly Online? A Troubleshooting Checklist That Actually Works.

2. SPA rewrites breaking CSS or JS

Single-page app routing often rewrites unknown paths to index.html. That is useful for client-side navigation, but dangerous if it catches requests for real asset files. If /assets/app.js is missing and the server returns your app shell HTML instead, the browser reports a JavaScript MIME type problem even though the deeper problem is routing.

The fix is usually to separate HTML route rewrites from asset path handling. Static assets should return the actual file or a real 404, not your main HTML page.

3. Object storage or CDN metadata problems

When files are uploaded to storage-backed hosting, the object metadata may define the final content type. If your upload process marks everything as generic binary data or leaves types blank, browsers may not process the files correctly.

This tends to surface after:

• manual uploads through a dashboard,
• scripted deployments with incomplete metadata settings,
• migrations between storage layers,
• CDN caches persisting old headers after a fix.

After updating headers at origin, invalidate or refresh the relevant cache layer if needed.

4. API endpoints expected to return JSON

In API debugging, content type issues often point to upstream errors. A frontend may call a JSON endpoint but receive an HTML login page, proxy error document, or default exception page instead. The payload shape is wrong, but the header often reveals the problem first.

Check these signals together:

• HTTP status code
• Content-Type
• Response body preview
• Authentication or redirect behavior

If the endpoint should return JSON, make sure success and error responses are both designed intentionally.

5. SVG icons not rendering consistently

SVG can fail in ways that look unrelated to MIME types. If the file opens directly in a tab but not through an image tag, inspect whether the server is sending image/svg+xml and whether the asset URL is correct. Also confirm that no image optimization layer is rewriting or blocking the file.

6. Deployment reviews and stakeholder previews

Preview links are useful only when they behave like production. During review, a page with broken styling or scripts can look like an application bug when the real issue is the host serving the wrong headers. If you regularly share standalone pages, staging builds, or HTML previews, add content-type checks to your basic release checklist.

Related reading: Static Site Preview Environments: Best Tools for Staging Front-End Changes and HTML Preview Link Tools Compared: Fastest Ways to Share a Web Page for Review.

When to revisit

Use this section as your action-oriented maintenance checklist. MIME types do not change every week, but the environments that serve your files do.

Revisit this reference when any of the following happens:

• You change hosting providers: different platforms may infer or store content types differently.
• You add a CDN or reverse proxy: headers can be cached, modified, or normalized in transit.
• You move from local dev to production: local servers often hide configuration gaps that production exposes.
• You adopt SPA rewrites or edge routing: asset requests can accidentally fall through to HTML responses.
• You script uploads to object storage: deployment automation may need explicit metadata handling.
• You introduce module scripts, manifests, or SVG-heavy UI assets: stricter browser handling makes header mistakes more visible.
• You see browser console errors mentioning MIME type, module loading, or refused stylesheets: that is the prompt to inspect headers before changing application code.

A practical workflow for future debugging:

1. Start with the failing URL in the browser’s Network panel.
2. Confirm the response status code.
3. Check the response Content-Type.
4. Preview the actual response body.
5. Verify whether the server returned the intended file, a fallback page, or an error document.
6. Check cache layers if the origin appears correct.
7. Fix the server or hosting rule before changing front-end code.

If you routinely deploy standalone HTML files, landing pages, or static front-end bundles, it is worth reviewing your hosting setup end to end. These guides can help with adjacent decisions: How to Deploy a Single HTML File with a Custom Domain: Step-by-Step Options, HTML File Hosting Pricing Guide: Free Tiers, Paid Plans, and Hidden Limits, and Best HTML File Hosting Platforms in 2026: Features, Limits, and Use Cases Compared.

The durable takeaway is simple: for HTML, CSS, JS, JSON, and SVG, correct MIME types are not optional polish. They are part of making the asset load at all. When a static site or web app breaks after deployment, checking the Content-Type header is one of the fastest high-signal debugging steps you can take.