WASM file serving with incorrect content type on GitHub Pages

Other Questions Github
1

I’m having trouble getting my WebAssembly app to work on GitHub Pages. The app is built with Rust and uses macroquad for rendering to HTML5 canvas. Everything runs fine when I test it locally with a simple HTTP server, but once deployed to GitHub Pages I get a MIME type error.

The error message says: TypeError: WebAssembly: Response has unsupported MIME type 'text/html; charset=utf-8' expected 'application/wasm'

Here’s my GitHub Actions workflow:

name: Deploy App
on:
  push:
    branches: [main]

permissions:
  contents: write
  pages: write
  
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
          target: wasm32-unknown-unknown
      - name: Compile
        run: cargo build --release --target wasm32-unknown-unknown
      - name: Setup Deploy Files
        run: |
          mkdir dist
          cp target/wasm32-unknown-unknown/release/calculator_app.wasm dist/
          cp main.html dist/
      - name: Publish
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: dist

And my HTML file:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Calculator</title>
    <style>
        body { margin: 0; background: #333; }
        canvas { display: block; }
    </style>
</head>
<body>
    <canvas id="canvas"></canvas>
    <script src="https://not-fl3.github.io/miniquad-samples/mq_js_bundle.js"></script>
    <script>
        load("calculator_app.wasm");
    </script>
</body>
</html>

Locally it works with: cargo build --release --target wasm32-unknown-unknown && basic-http-server .

Why is GitHub Pages not serving the WASM file with the correct MIME type?

2

GitHub Pages doesn’t handle WASM files right out of the box. I hit this same problem with my Rust WebAssembly stuff. Don’t rely on server config - it’s flaky on GitHub Pages. Just fetch the WASM file manually with explicit headers instead. Ditch your load() call and write a function that uses fetch() to grab the .wasm file, then run WebAssembly.instantiate() on it. You’re working with the binary data directly in JS this way, so you skip the MIME type mess completely. Plus it works on other hosting platforms too.

3

Hit this exact problem twice with different Rust projects on GitHub Pages. It’s not just MIME types - GitHub Pages processes files during deployment and can mess up binary files or serve them wrong. Here’s what fixed it for me: add a .nojekyll file to your dist folder before deployment. Jekyll processing screws with binary files even when you’re not using Jekyll. Just add touch dist/.nojekyll to your workflow after the mkdir command. This makes GitHub Pages skip preprocessing and serve files as-is. Also rename main.html to index.html in dist or GitHub Pages won’t find your entry point. The .nojekyll file plus proper naming fixed my deployment without needing manual fetch calls or external hosting.

4

Had this exact problem with my rust/wasm project last year. GitHub Pages doesn’t recognize .wasm files and serves them as text/html instead of application/wasm. Here’s what fixed it for me - add a _headers file to your dist directory before deploying. Create _headers (no extension) with:

*.wasm
  Content-Type: application/wasm

Then modify your workflow to copy this file to dist. Add cp _headers dist/ after your mkdir command. Just make sure the _headers file is in your repo root first. This forces GitHub Pages to serve wasm files with the right MIME type. Way cleaner than renaming files or other hacks.

5

The Problem:

You’re encountering difficulties deploying your Rust-based WebAssembly application to GitHub Pages due to MIME type issues. Locally, your application functions correctly, but on GitHub Pages, you receive a TypeError: WebAssembly: Response has unsupported MIME type 'text/html; charset=utf-8' expected 'application/wasm' error. This indicates that GitHub Pages is serving your .wasm file with the incorrect MIME type.

:thinking: Understanding the “Why” (The Root Cause):

GitHub Pages has limitations in its default configuration for serving less common file types like WebAssembly modules (.wasm). It might not automatically recognize and serve .wasm files with the correct application/wasm MIME type. Relying on GitHub Pages’ default settings for handling .wasm files is unreliable and often leads to deployment issues. Furthermore, GitHub Pages’ build process can sometimes interfere with binary files, making direct deployment problematic.

:gear: Step-by-Step Guide:

  1. Migrate to a More Robust Hosting Platform: The most reliable solution is to avoid the inherent limitations of GitHub Pages for deploying WebAssembly applications. Services like Netlify or Vercel are specifically designed to handle various file types, including .wasm, seamlessly. They offer robust deployment pipelines and automatic configuration for the correct MIME types, eliminating the need for manual workarounds.

  2. Set up a Continuous Deployment Workflow: This typically involves creating a workflow (e.g., using GitHub Actions) that:

    • Compiles your Rust code targeting wasm32-unknown-unknown.
    • Copies the compiled .wasm file and associated HTML/JavaScript files to a deployment directory.
    • Deploys the contents of the deployment directory to your chosen platform (Netlify or Vercel). This is usually accomplished through the platform’s API or CLI.

  3. Configure Your Chosen Platform: Configure your Netlify or Vercel project to appropriately handle the WebAssembly deployment. This might involve setting specific build commands or build settings within the platform’s dashboard. Both Netlify and Vercel generally handle the MIME type assignment correctly.

  4. Test Your Deployment: After setting up the workflow and deploying to the chosen platform, thoroughly test your application to ensure it functions as expected.

:mag: Common Pitfalls & What to Check Next:

  • Build Process Errors: Double-check your Rust build process to ensure that the .wasm file is being compiled correctly and that the output path in your build scripts matches the path your deployment workflow is using.

  • File Paths: Verify that the paths to your .wasm and HTML files in your deployment script are accurate and relative to the root of your deployment directory.

  • Caching: Clear any browser cache or service worker cache after deploying to ensure you are loading the newest version of your application.

  • Alternative Approaches (Less Recommended): While migrating to a platform like Netlify or Vercel is strongly advised, if you absolutely must remain on GitHub Pages, explore solutions like creating a _headers file to specify the MIME type manually. However, this is not a recommended long-term solution due to potential inconsistencies and limitations.

:speech_balloon: Still running into issues? Share your (sanitized) config files, the exact command you ran, and any other relevant details. The community is here to help!

6

github pages can mess up wasm files. try putting a .htaccess in your dist folder with AddType application/wasm .wasm, or go for a _headers file. another way is to rename your wasm file to .bin and fetch it manually in js. just skip using load.

7

check your file path first. github pages sometimes adds extral dir, so your wasm file might not be where you think it is. open dev tools and see what’s being requested - ur probably getting a 404 that returns html instead of ur wasm file.

8

This topic was automatically closed 24 hours after the last reply. New replies are no longer allowed.