Fix Module Worker MIME Errors at the URL Boundary

TLDR: When a browser says a JavaScript module has the MIME type text/html, the worker code may be fine. The requested URL often fell through to an application's HTML route. Let the bundler emit and import the worker URL, then verify the response body and content type instead of trusting a successful status code.

Symptom

A PDF worker failed before initialization with strict MIME checking. The network request returned HTML where the browser expected JavaScript. Because single-file extraction and batch extraction configured workers separately, the failure could appear in only one workflow.

The tempting response is to inspect imports inside the worker. That starts too late. The browser never parsed the worker module.

Cause

The application accepted a worker URL from runtime configuration. That URL was stale or invalid for the current production bundle. The development server used a single-page application fallback, so an unknown asset route returned the main HTML document, sometimes with a successful status.

The browser correctly rejected that response. A 200 status proved only that a server answered, not that the requested module existed.

Fix

Make the build tool own the asset address and use the same imported URL in every entry path.

import pdfWorkerUrl from "pdfjs-dist/build/pdf.worker.min.mjs?url";
pdfjs.GlobalWorkerOptions.workerSrc = pdfWorkerUrl;

This allows development and production builds to apply their own hashing, base path, and asset placement. It also removes drift between single-document and batch controllers.

Do not silently prefer an injected URL merely because it is present. If overrides are necessary for deployment, validate that the response is JavaScript before installing it, and report a configuration error early.

Verification

Check more than the console:

1. Build the production bundle and confirm the emitted worker asset exists.
2. Inspect the worker request's Content-Type and first bytes.
3. Exercise every entry path that configures the library.
4. Confirm a missing URL fails visibly rather than loading the HTML shell.

The transferable rule is simple: module MIME errors are frequently routing errors disguised as JavaScript errors. Debug the requested resource boundary first. Status codes alone are weak evidence on servers with fallback routing.

One additional guard helps during development: log the resolved worker URL once, near library initialization. When a regression appears only after deployment, that value immediately distinguishes a bundling problem from a worker execution problem. Keep the log free of document data, remove noisy repetition, and make both upload paths call the same initializer. Centralizing this small configuration prevents the next build from fixing one controller while leaving another pointed at an obsolete asset.