If a file on your site downloads when it should open in the browser, opens as gibberish when it should download, or a browser refuses to load a script with a "MIME type" error, the server is sending the wrong file type. This guide explains how to add MIME types and Apache handlers in cPanel, when you actually need them, and how to check the fix worked.
What MIME types and handlers are
When the server sends a file, it attaches a label saying what kind of file it is -- the MIME type (also called the content type). The browser decides what to do based on that label, not on the file name:
text/html-- show it as a web page.image/webp-- display it as an image.application/pdf-- open it in the PDF viewer.application/octet-stream-- "just some data": download it.
An Apache handler is different: it tells the server to process a file before sending it, rather than send it as-is. The best-known example is PHP -- a .php file is run, and only its output is sent. Handlers also switch on server-side includes and CGI scripts.
Our servers run LiteSpeed, which follows the same MIME type and handler rules as Apache, so cPanel's tools work the same way here.
Do you need to add one?
Probably not -- the server already knows hundreds of file types. Before adding anything, check what your file is currently being sent as:
- Open a private browser window and go to the file's full address, for example
https://example.com/files/app.webmanifest. - Press F12, open the Network tab and reload.
- Click the file in the list and look under Response Headers for content-type.
Or from Advanced > Terminal:
curl -sI https://example.com/files/app.webmanifest | grep -i content-type
If the type is already correct, the problem is elsewhere (usually caching, a CDN, or the code linking to the file). If it's wrong or missing -- often it'll say application/octet-stream or text/plain for a type the server doesn't recognize -- add a MIME type.
How to add a MIME type in cPanel
- Log in to cPanel (from the client area: Services > My Services, choose your plan, then Log in to cPanel).
- Go to Advanced > MIME Types.
- Scroll down to System MIME Types first and search the page (Ctrl+F, or Cmd+F on a Mac) for your extension. If it's already there with the right type, you don't need to add it.
- Back at the top, under Create a MIME Type, type the type in the MIME Type box, for example
application/manifest+json. - Type the extension in the Extension(s) box, without the dot, for example
webmanifest. You can enter several extensions separated by spaces. - Click Add.
Your entry appears under User Defined MIME Types and takes effect straight away. Test the file again in a private window.
MIME types customers commonly need
| Extension | MIME type | Why you'd add it |
|---|---|---|
webmanifest | application/manifest+json | Web app manifests for "add to home screen". |
mjs | text/javascript | JavaScript modules. Browsers refuse to run a module sent with the wrong type. |
wasm | application/wasm | WebAssembly files, used by some games, viewers and tools. |
woff2 | font/woff2 | Web fonts. |
vcf | text/vcard | Contact cards visitors can save to their phone. |
ics | text/calendar | Calendar events visitors can add to their calendar. |
apk | application/vnd.android.package-archive | Android app downloads. |
gpx | application/gpx+xml | GPS route files for hiking and cycling sites. |
Many of these will already be in the system list; only add the ones that aren't.
Forcing a file to download instead of opening
If you want visitors to download files that browsers would normally display -- for example a folder of PDFs or text files -- you can map the extension to application/octet-stream. But a MIME type applies to every file with that extension on the whole site, so this affects all your PDFs. A more targeted option is to put a small .htaccess file in just the downloads folder:
<FilesMatch "\.(pdf|txt|csv)$">
Header set Content-Disposition "attachment"
</FilesMatch>
Or simply add the download attribute to the link in your page: <a href="/files/price-list.pdf" download>.
How to add an Apache handler
- In cPanel, go to Advanced > Apache Handlers.
- Under Create an Apache Handler, type the handler name in the Handler box.
- Type the extension(s) in the Extension(s) box, separated by spaces.
- Click Add. The handler appears under User Defined Apache Handlers.
You can only use handlers the server already knows about -- this page doesn't let you create brand-new ones. The standard names are:
| Handler | What it does |
|---|---|
server-parsed | Processes server-side includes (SSI) such as <!--#include virtual="/footer.html" -->. |
cgi-script | Runs the file as a CGI script (for example old Perl scripts). |
default-handler | Sends the file as plain content, without running it. |
send-as-is | Sends a file that contains its own HTTP headers. Rarely needed. |
type-map, imap-file | Old content-negotiation and image-map features. Rarely needed today. |
Example: server-side includes in .html files
Older hand-built sites sometimes use SSI to share one header and footer across every page. Files ending in .shtml are usually already set up for this -- check the System Apache Handlers table. If your pages end in .html instead, add a handler with Handler server-parsed and Extension(s) html. Every .html page is then scanned for include commands, which is slightly more work for the server but negligible for a small site.
What about running PHP inside .html files?
People often ask for this when moving an old site. We don't recommend it: the correct PHP handler depends on the PHP version and selector your domain uses, and it can silently break when the PHP version changes. The reliable fix is to rename the pages to .php and add 301 redirects from the old .html addresses, so bookmarks and search rankings carry over -- see How to Set Up a 301 Redirect in cPanel. If you really can't rename them, open a ticket and we'll tell you the right handler line for your account's setup.
Where these settings are saved
Both tools write simple lines into the .htaccess file in public_html, like these:
AddType application/manifest+json .webmanifest
AddHandler server-parsed .html
That means you can also add these lines by hand, or put them in a .htaccess in one folder so they only apply there. It also means a mistake in .htaccess -- or replacing the file with an old copy -- can remove them. Keep a backup of .htaccess before editing it; see How to Show Hidden Files (.htaccess) in cPanel File Manager.
How to remove a MIME type or handler
- Open Advanced > MIME Types or Apache Handlers.
- In the User Defined table, click Delete next to the entry.
- Confirm.
You can't delete entries in the System tables. To override a system type, add your own user-defined entry for the same extension.
Troubleshooting
I added the MIME type but the browser still shows the old one
- Test in a private window -- browsers and LiteSpeed Cache can hold on to the old response. For WordPress, purge the cache.
- If you use Cloudflare or another CDN, purge the file in the CDN too.
- Check
.htaccessfor an olderAddTypeorForceTypeline for the same extension, and for a folder-level.htaccessthat overrides the main one.
The browser shows "Refused to execute script ... MIME type ('text/html') is not executable"
This usually isn't a MIME type problem at all -- the browser asked for a .js file and got an HTML page back, most often a 404 page or a login page. Open the script's address directly; if you see a web page instead of code, fix the path or the missing file.
My site shows a 500 error after adding a handler
Delete the handler you just added. If the error remains, check public_html/.htaccess for a broken line and restore your backup copy. See 500 Internal Server Error: What It Means and How to Fix It.
PHP code shows as plain text in the browser
The PHP handler for that file isn't active -- often because an old AddHandler or AddType line from a previous host is in .htaccess. Remove old PHP handler lines that you didn't add through MultiPHP Manager, then re-apply your version in Software > MultiPHP Manager. Change any passwords that were in the exposed file.
Common questions
Do MIME types affect email attachments?
No. These settings only change how your website sends files.
Do these settings apply to subdomains?
They're written to public_html/.htaccess, so they apply to folders under public_html. A subdomain whose document root is outside public_html needs its own lines in its own .htaccess.
Are handlers a security risk?
They can be. Mapping an extension that visitors can upload (such as .jpg or .txt) to a script handler would let an uploaded file run as code. Only add handlers for extensions that you control.
Related guides
- How to Show Hidden Files (.htaccess) in cPanel File Manager
- How to Set Up a 301 Redirect in cPanel
- How to Change Your PHP Version in cPanel
- How to Edit a File in cPanel File Manager
- 500 Internal Server Error: What It Means and How to Fix It
Still stuck? Open a support ticket and the Instant Access Internet Services team will help.
