OpenCV.js cascade file load in Node: mount NODEFS first

You load OpenCV.js into a Node process, point CascadeClassifier at lib/haarcascade_frontalface_default.xml, and the console answers with Can't open file ... in read mode from persistence.cpp — while fs.readFileSync opens the very same path without complaint. The path is correct; the filesystem it resolves against is not. OpenCV.js is a WebAssembly module carrying its own private, in-memory filesystem, and your Node paths never reach it. This guide walks the failure from symptom to fix: mount your real working directory into that virtual filesystem with NODEFS, change the module's working directory, and load the cascade again. It also covers the errno 44 FS error from cv.FS.chdir(process.cwd()), the abort you get when the browser build runs in Node, and where the frames for the classifier should come from.

The symptom and what it tells you

The console line looks like this:

[ERROR:0@0.074] global /build/master-contrib_docs-lin64/opencv/modules/core/src/persistence.cpp (505) open Can't open file: 'lib/haarcascade_frontalface_default.xml' in read mode

Three call forms produce the identical line: new cv.CascadeClassifier("lib/haarcascade_frontalface_default.xml"), the same with path.resolve(...) in front, and new cv.CascadeClassifier().load("lib/haarcascade_frontalface_default.xml"). Meanwhile readFileSync("lib/haarcascade_frontalface_default.xml") returns the file's bytes. That pair of facts is the whole diagnosis: the file exists on the real disk, and the loader is not looking at the real disk.

There is one more clue. The module exposes Emscripten file hooks such as cv.FS_createLazyFile on its cv.FS object. The filesystem layer is reachable from your script — and that is exactly where the repair belongs.

Why a valid Node path still fails

Emscripten compiles OpenCV into WebAssembly, and every file the module opens — a cascade XML included — goes through the module's own filesystem, an in-memory tree that starts essentially empty. The persistence layer calls its open inside that sandbox, where lib/ and any absolute host path simply do not exist. Node's fs module, meanwhile, reads the real disk. One string, two filesystems: that is why all three load forms fail identically and why path.resolve changes nothing — it produces a perfectly correct path to a directory the sandbox has never seen.

Model-load path failures are not an OpenCV.js quirk. Native stacks hit the same wall at deployment time, as machine vision model file paths and deployment errors shows, and acquisition scripts hit it across operating systems, as Python image file path errors across operating systems records. The OpenCV.js twist is harsher: the file exists and the process can read it, and only the sandbox cannot.

The fix: mount NODEFS, then chdir

Mount the real working directory into the virtual filesystem, point the module's working directory at the mount, then load the same relative path as before.

1. Keep a reference to the module's filesystem object.
2. Create the mount point inside the virtual filesystem.
3. Mount your real working directory onto it with the NODEFS backend.
4. Change the module's working directory to the mount point.
5. Construct the classifier with the same relative path.

// cv is the OpenCV.js module, already loaded. runDetection() further down is
// your own function; every other name here is OpenCV.js / Emscripten API.
const emscriptenFs = cv.FS;              // Emscripten filesystem object
const virtualMountFolder = "/local";     // string: path inside the virtual filesystem

emscriptenFs.mkdir(virtualMountFolder);  // the mount point must exist first
emscriptenFs.mount(
  emscriptenFs.filesystems.NODEFS,       // Node-backed backend, reads the real disk
  { root: process.cwd() },               // the real directory to expose
  virtualMountFolder
);
emscriptenFs.chdir(virtualMountFolder);  // relative paths now resolve from /local

const faceClassifier = new cv.CascadeClassifier("lib/haarcascade_frontalface_default.xml");

From this point every file under process.cwd() is reachable from inside the module. The relative path lib/haarcascade_frontalface_default.xml resolves to /local/lib/haarcascade_frontalface_default.xml in the virtual tree, and NODEFS maps that straight onto your disk. Run the script again: the persistence.cpp line disappears and the constructor is silent.

Prove the load worked

A silent constructor is necessary but not sufficient, because a failed load does not throw at construction — it surfaces later, on the first detection. Guard that call once:

// Test: one detection pass, run exactly as production runs it.
// detectMultiScale() over an empty cascade throws instead of returning
// detections, so the first call tells you whether the file really loaded.
try {
  runDetection(faceClassifier, frame);   // your function wrapping detectMultiScale()
  console.log("cascade loaded and ran");
} catch (err) {
  console.error("cascade never loaded:", err);
}

If the catch fires, the cascade object is empty and the load path is still wrong — walk the mount steps again. If the success line prints, the mount holds for the process lifetime. Mount once at startup, never per request.

The chdir shortcut and errno 44

The OpenCV Node examples load cascades with a bare relative path and appear to mount nothing. They get away with it because the module's working directory already lines up with the host's — in practice through cv.FS.chdir(process.cwd()) — and that only works when the directory process.cwd() returns exists inside the virtual filesystem. On builds where it does not, chdir throws an object rather than an Error:

{ node: undefined, setErrno: [Function (anonymous)], errno: 44, message: 'FS error' }

Treat the bare chdir as unreliable across builds. The mount creates /local first, so chdir into it always succeeds. That is the dependable form, and it is the one to ship.

The mount aborts: you have the browser build

If emscriptenFs.mount(...) dies with:

ERROR abort(Assertion failed: undefined). Build with -s ASSERTIONS=1 for more info.

the backend you passed is undefined: this bundle ships no cv.FS.filesystems.NODEFS. NODEFS is the Node-only backend; browser builds exclude it, and a browser has no disk to mount regardless. Decide by environment. In Node, load the Node build of OpenCV.js so NODEFS is present. In a browser, serve the XML from your web server and load it by its URL, or fetch its bytes into the virtual filesystem before constructing the classifier.

Feeding the classifier: where frames come from

The cascade needs frames, and in this stack they do not come through OpenCV's own capture — why OpenCV VideoCapture cannot open a GigE Vision camera explains the interface reason. Grab frames from the camera SDK and hand the pixels over as buffers; barcode image buffer decoding covers keeping those pixels intact through the decode. Buffer-fed frames go straight into a Mat and never touch the virtual filesystem, so the mount matters for the cascade file, not for the image stream.

Frames for a host-side detector come from area scan cameras over GigE or USB3.

The other route removes the host from the loop. Smart cameras run the inspection on the device and report results over the network, so no cascade file exists to mount. When the deliverable is the inspection rather than OpenCV specifically, that is the simpler architecture — and once images flow, smart camera misses first images after load explains the ready gate to set on the receiving end.

When this fix is the wrong fix

Three cases where the mount will not save you:

• readFileSync fails too. The file is genuinely missing, misnamed or unreadable. Fix that first; a mount cannot expose what the disk does not have.
• The app is packaged or containerised. process.cwd() at runtime points where the launcher started the process, not at your project root. Mount the directory that actually contains lib/ in the deployed layout.
• You control the host and need throughput. WebAssembly adds a filesystem layer and costs speed. A native OpenCV build reads the cascade directly, and a smart camera moves detection on-device. Keep OpenCV.js in Node for pure-JavaScript deployments where native modules are not allowed.

Symptom to action at a glance

Prevention checklist

• Mount once at startup, before any classifier is constructed. Every later load inherits the virtual working directory.
• Keep cascades under one lib/ folder inside the mounted root. Relative paths after chdir stay short and independent of the host layout.
• Log the virtual working directory at boot. One console line turns this whole failure class into a five-second answer.
• Pin your project to the Node build of OpenCV.js. The browser bundle fails at the mount instead of the load, which costs an afternoon to trace.
• Mount the runtime directory, not the development cwd. Packaged apps start wherever the launcher puts them.

To feed the detector, the camera finder filters by interface and resolution, and the configurator walks camera, lens and light in one pass. For a review of the whole pipeline, the contact page reaches the applications team, and further integration notes sit on the systems topic page.