fix: graceful error handling for GLM-OCR external data incompatibility

ijbo · ijbo · commit 4caa4236fbda · 2026-03-23T16:34:46.000+09:00
diff --git a/ai-worker-glm-ocr.js b/ai-worker-glm-ocr.js
@@ -55,12 +55,23 @@ async function loadModel() {
             }
         }
 
-        // 2. Check WebGPU
+        // 2. Check WebGPU — GLM-OCR requires WebGPU (q4f16 external data files
+        //    cannot be loaded by WASM's Module.MountedFiles)
         if (typeof navigator !== "undefined" && navigator.gpu) {
             const adapter = await navigator.gpu.requestAdapter();
             if (adapter) device = "webgpu";
         }
 
+        if (device !== "webgpu") {
+            self.postMessage({
+                type: "error",
+                message: "GLM-OCR requires WebGPU which is not available in this browser. " +
+                    "Please use Chrome 113+, Edge 113+, or another WebGPU-capable browser. " +
+                    "Alternatively, use Granite Docling or Florence-2 which work without WebGPU.",
+            });
+            return;
+        }
+
         // Progress callback factory
         const progressCb = (label) => (progress) => {
             if (progress.status === "progress") {
@@ -108,16 +119,43 @@ async function loadModel() {
             });
         }
 
-        // 3. Load with fallback
+        // 3. Load with fallback to onnx-community mirror
         try {
             await loadFromHost();
         } catch (primaryErr) {
+            // Detect the known external-data incompatibility with onnxruntime-web 1.19.x
+            const errMsg = primaryErr.message || "";
+            if (errMsg.includes("MountedFiles") || errMsg.includes("external data file")) {
+                self.postMessage({
+                    type: "error",
+                    message: "GLM-OCR is temporarily unavailable — the model's quantized weights require " +
+                        "a newer ONNX Runtime version that isn't yet compatible with this library. " +
+                        "Please use Granite Docling or Florence-2 for OCR in the meantime.",
+                });
+                return;
+            }
+
             console.warn(`textagent model failed: ${primaryErr.message}. Falling back to ${MODEL_ORG_FALLBACK}…`);
             self.postMessage({ type: "status", message: `Falling back to ${MODEL_ORG_FALLBACK} models…` });
             MODEL_ID = MODEL_ID.replace('textagent/', MODEL_ORG_FALLBACK + '/');
             processor = null;
             model = null;
-            await loadFromHost();
+
+            try {
+                await loadFromHost();
+            } catch (fallbackErr) {
+                const fbMsg = fallbackErr.message || "";
+                if (fbMsg.includes("MountedFiles") || fbMsg.includes("external data file")) {
+                    self.postMessage({
+                        type: "error",
+                        message: "GLM-OCR is temporarily unavailable — the model's quantized weights require " +
+                            "a newer ONNX Runtime version that isn't yet compatible with this library. " +
+                            "Please use Granite Docling or Florence-2 for OCR in the meantime.",
+                    });
+                    return;
+                }
+                throw fallbackErr;
+            }
         }
 
         self.postMessage({ type: "loaded", device: device });
diff --git a/changelogs/CHANGELOG-glm-ocr-fix.md b/changelogs/CHANGELOG-glm-ocr-fix.md
@@ -0,0 +1,44 @@
+# GLM-OCR Graceful Error Handling
+
+**Date:** 2026-03-23
+
+## Summary
+
+Added graceful error handling for the GLM-OCR model when it fails to load due to an
+incompatibility between `transformers.js@4.0.0-next.8` (the only version supporting the
+`glm_ocr` model type) and its bundled `onnxruntime-web@1.19.x` which cannot load external
+`.onnx_data` weight files in the browser.
+
+## Problem
+
+- GLM-OCR's quantized weights (`q4f16`) are stored in external `.onnx_data` files
+- ONNX Runtime Web requires explicit `externalData` session options to load these files
+  in the browser (confirmed by official ONNX Runtime docs)
+- `transformers.js@4.0.0-next.8` does not pass `externalData` options to `InferenceSession.create()`
+- This caused a cryptic `Module.MountedFiles is not available` error on every page load
+
+## Changes
+
+### Modified Files
+- `ai-worker-glm-ocr.js` — Added WebGPU guard + `MountedFiles` / `external data file`
+  error detection with a clear user-facing message
+- `public/ai-worker-glm-ocr.js` — Synced copy
+
+### What Changed
+- **WebGPU guard:** If WebGPU is unavailable, the worker now returns a clear error
+  suggesting Granite Docling or Florence-2 as alternatives
+- **External data error detection:** Catches the specific `MountedFiles` / `external data file`
+  error pattern from ONNX Runtime and shows a user-friendly message:
+  > "GLM-OCR is temporarily unavailable — the model's quantized weights require a newer
+  > ONNX Runtime version that isn't yet compatible with this library."
+- **Prevents fallback retry:** The old code would fail on `textagent/GLM-OCR-ONNX`, then
+  retry on `onnx-community/GLM-OCR-ONNX` with the same result. Now it detects the error
+  immediately and stops
+- **Clears consent flag:** The error response triggers consent cleanup in `ai-assistant.js`,
+  preventing stuck retry loops on page reload
+
+## Resolution Path
+
+The model will work automatically once `transformers.js` v4 stable releases with
+`onnxruntime-web ≥ 1.22` and adds `externalData` session option plumbing. At that point,
+only the `TRANSFORMERS_URL` version string needs updating.
diff --git a/public/ai-worker-glm-ocr.js b/public/ai-worker-glm-ocr.js
@@ -55,12 +55,23 @@ async function loadModel() {
             }
         }
 
-        // 2. Check WebGPU
+        // 2. Check WebGPU — GLM-OCR requires WebGPU (q4f16 external data files
+        //    cannot be loaded by WASM's Module.MountedFiles)
         if (typeof navigator !== "undefined" && navigator.gpu) {
             const adapter = await navigator.gpu.requestAdapter();
             if (adapter) device = "webgpu";
         }
 
+        if (device !== "webgpu") {
+            self.postMessage({
+                type: "error",
+                message: "GLM-OCR requires WebGPU which is not available in this browser. " +
+                    "Please use Chrome 113+, Edge 113+, or another WebGPU-capable browser. " +
+                    "Alternatively, use Granite Docling or Florence-2 which work without WebGPU.",
+            });
+            return;
+        }
+
         // Progress callback factory
         const progressCb = (label) => (progress) => {
             if (progress.status === "progress") {
@@ -108,16 +119,43 @@ async function loadModel() {
             });
         }
 
-        // 3. Load with fallback
+        // 3. Load with fallback to onnx-community mirror
         try {
             await loadFromHost();
         } catch (primaryErr) {
+            // Detect the known external-data incompatibility with onnxruntime-web 1.19.x
+            const errMsg = primaryErr.message || "";
+            if (errMsg.includes("MountedFiles") || errMsg.includes("external data file")) {
+                self.postMessage({
+                    type: "error",
+                    message: "GLM-OCR is temporarily unavailable — the model's quantized weights require " +
+                        "a newer ONNX Runtime version that isn't yet compatible with this library. " +
+                        "Please use Granite Docling or Florence-2 for OCR in the meantime.",
+                });
+                return;
+            }
+
             console.warn(`textagent model failed: ${primaryErr.message}. Falling back to ${MODEL_ORG_FALLBACK}…`);
             self.postMessage({ type: "status", message: `Falling back to ${MODEL_ORG_FALLBACK} models…` });
             MODEL_ID = MODEL_ID.replace('textagent/', MODEL_ORG_FALLBACK + '/');
             processor = null;
             model = null;
-            await loadFromHost();
+
+            try {
+                await loadFromHost();
+            } catch (fallbackErr) {
+                const fbMsg = fallbackErr.message || "";
+                if (fbMsg.includes("MountedFiles") || fbMsg.includes("external data file")) {
+                    self.postMessage({
+                        type: "error",
+                        message: "GLM-OCR is temporarily unavailable — the model's quantized weights require " +
+                            "a newer ONNX Runtime version that isn't yet compatible with this library. " +
+                            "Please use Granite Docling or Florence-2 for OCR in the meantime.",
+                    });
+                    return;
+                }
+                throw fallbackErr;
+            }
         }
 
         self.postMessage({ type: "loaded", device: device });
