MIME Types: Nginx, Apache, and Caddy Configuration

MIME Types: Nginx, Apache, and Caddy Server Configuration Guide

Server MIME type configuration controls what Content-Type header every file gets. When a web server delivers a file, the Content-Type response header tells the browser how to handle it: render the content, execute it as a script, or trigger a download. Most servers ship with a built-in MIME type table covering common formats, but newer formats added after the type database was last updated require explicit configuration. AVIF images, WebAssembly modules, and WOFF2 fonts all require manual entries on many server versions.¹ Missing or wrong MIME types cause real failures: browsers refuse to execute WebAssembly served without application/wasm, reject cross-origin fonts with incorrect types, and may refuse JavaScript under strict CSP. Testing your configuration with curl before deployment catches mismatches before they reach production users.

Types that need explicit server configuration

Most servers ship with MIME type tables written years before modern formats existed, which means the bundled configuration files that ship with Nginx, Apache, and Caddy reflect the web format landscape of a decade ago rather than today.² Nginx's bundled mime.types file, Apache's mime.types database, and Caddy's built-in defaults all cover JPEG, PNG, HTML, CSS, and JSON. Yet several widely-used formats are absent from older installs. AVIF images (image/avif) require an explicit entry in Nginx 1.17 and older. WebAssembly files (application/wasm) are missing from most server defaults shipped before 2019. WOFF2 fonts (font/woff2) were absent from Apache's default MIME database until recently.

Strict browser enforcement for modern formats

Furthermore, browser enforcement for these types is strict: application/wasm triggers a hard compile-time error if wrong, while incorrect font MIME types produce silent failures with no browser error message. Building on this, a post-deployment curl audit is the only reliable way to confirm all types are configured correctly. Run curl -sI against representative URLs for each format your server delivers, and compare every Content-Type response header against the expected IANA-registered value. Automating this check in a deployment pipeline catches regressions before they reach production users.

Testing MIME headers with curl

Verifying MIME type headers requires an HTTP response, not a file system check. Run curl -sI https://example.com/assets/app.wasm and read the Content-Type line in the response headers. The -I flag sends a HEAD request, returning only headers without downloading the file body. For local development, run curl -sI http://localhost:3000/path/to/file.avif. Checking several file types in sequence is faster with individual HEAD requests per extension: request one representative file of each format and inspect its Content-Type. Conversely, browser developer tools show Content-Type in the Network panel, but you need a page that actively loads the file, making curl more reliable for systematic auditing. Record the expected and actual Content-Type for each format in a checklist before signing off on a new server configuration.

Common misconfigurations and detection

Three misconfigurations appear across all server types. The first is serving WASM files as application/octet-stream. This happens when the server's MIME table has no application/wasm entry, and the server falls back to its default binary type. Browsers reject this with a hard error. The second is serving AVIF images as application/octet-stream rather than image/avif. The third is serving WOFF2 fonts as application/octet-stream rather than font/woff2. Furthermore, WOFF2 loaded cross-origin requires both the correct MIME type and an Access-Control-Allow-Origin header. Browsers fail silently on incorrect font MIME types: no console error appears, the font simply fails to load and the page uses its CSS fallback. Detecting this requires checking the Network panel for the font request status and Content-Type value.

Caddy v2 MIME type configuration with the header directive

Caddy v2 ships with a built-in MIME type table that covers common formats.³ For newer formats absent from the built-in table, the header directive in a Caddyfile overrides Content-Type on matching responses without touching the global type table. Caddy's named path matchers let you scope each override to requests ending with a specific extension: the declaration @avif { path *.avif } defines a named matcher that a subsequent header directive references.

A complete Caddy override for AVIF and WebAssembly looks like this: define matchers using the @ prefix, then pair each matcher with header @matcher Content-Type "image/avif" or header @matcher Content-Type "application/wasm". Caddy evaluates matchers in the order directives appear in the site block, so place MIME overrides before the file_server directive that serves the static files. This approach changes only Content-Type for matched paths and leaves other response headers untouched.

Caddy's encode directive and already-compressed formats

Caddy's encode directive applies gzip or zstd HTTP compression to responses. It decides which responses to compress based on Content-Type; the default list includes text/html, application/json, and application/javascript. Adding AVIF or WebAssembly overrides with the header directive does not automatically add them to the encode compression list, which is correct behaviour since both formats are already compressed internally. Verify that encode does not apply a second compression pass to these formats by checking that the Content-Encoding header is absent from AVIF and WASM responses after the overrides take effect.

S3 and CloudFront static hosting MIME configuration

Amazon S3 paired with CloudFront is a common static hosting setup where MIME type configuration requires careful attention at the S3 layer, because CloudFront does not independently determine or correct Content-Type values. CloudFront passes the Content-Type header from the S3 origin response directly to the browser without modification, which means the MIME type stored in the object's ContentType metadata field in S3 is exactly what every browser receives on every edge node worldwide. Uploading files without specifying the content type causes S3 to default to application/octet-stream for formats it does not recognise by extension, triggering download prompts instead of inline rendering for images, fonts, and other displayable formats.

For AVIF images, set the content type to "image/avif" in the S3 upload parameters so that browsers render the image inline instead of triggering a download prompt. For WebAssembly binaries, set the content type to "application/wasm" to avoid the hard compile-time error browsers throw when the type is wrong. Adding these parameters to every upload in your CI pipeline prevents the application/octet-stream fallback from reaching users after each deployment, and it also ensures that any cache invalidation or re-upload during a rollback preserves the correct metadata.

Verifying MIME types on CloudFront distributions

After uploading with correct ContentType metadata, verify the CloudFront distribution by running curl -sI against the CloudFront URL rather than the S3 origin URL directly. CloudFront caches responses; if you previously served an object with the wrong Content-Type, create a CloudFront invalidation for the affected paths before retesting. Create the invalidation with aws cloudfront create-invalidation, passing your distribution ID and the path pattern "*.wasm", then wait for it to complete before running the curl verification.

Remember that the invalidation removes only the cached header value, not the underlying object, so a corrected S3 metadata write must land before the invalidation runs or the edge simply re-caches the wrong type. Ordering the write before the invalidation is the detail most deployments get wrong on the first attempt. CapyToolkit's MIME reference lists the expected Content-Type for every modern format so each curl check has a known target to compare against.

When to use this

Use this guide when setting up a new static file server, auditing an existing server configuration for MIME type mismatches, or verify server MIME types with curl when your server sends the wrong Content-Type.⁴

Examples

# Without explicit types, these files get application/octet-stream

types {
    image/avif  avif;
    application/wasm  wasm;
    font/woff2  woff2;
}