Haar cascade file not found on embedded camera: fix the ENOENT path

Your detection script stops on its second line: OSError: [Errno 2] ENOENT, raised by image.HaarCascade("frontalface", stages=25). Your parameters are not the problem, and neither is the camera. Errno 2 is the operating system reporting that the cascade file is not there: the loader resolved the argument to a concrete location on the embedded camera and found nothing to open. This guide decodes the error, walks the three causes in the order they occur on real hardware, gives the five-minute fix for each, and shows how to make model paths deterministic so the failure does not come back.

What errno 2 actually tells you

ENOENT is errno 2 in the standard C library: "no such file or directory". The loader ran, resolved what you passed into a concrete path, asked the operating system to open it, and the OS found nothing at that location. Everything downstream — the 25 cascade stages, the image pipeline, the detection itself — never executes. Treat it as a map problem, not a model problem.

The neighbouring errnos fail for different reasons and need different fixes:

Because errno 2 fires at file open, the stages=25 argument — a request for a 25-stage cascade — plays no part in it. Fix the location first; tune the stage count afterwards.

Cause 1: the stock cascade is missing from the ROM filesystem

On MicroPython-class vision boards the stock cascades are not loose files on an SD card. They live in a read-only ROM filesystem (ROMFS) image flashed together with the firmware, and a bare name such as frontalface is looked up inside that image and nowhere else.

Two things empty it: a firmware image older than the shipped examples, and a ROMFS image flashed without the default files. On this board family, the update that shipped the corrected examples also reset the ROM filesystem during the IDE upgrade — v4.7.0 did that step automatically — so a board flashed from an old image is the usual patient when code that ran a year ago now fails.

The fix takes two steps:

1. Update the IDE and flash the current firmware for the board.
2. Reset the ROM filesystem from the IDE menu: Tools → ROMFS → Reset ROMFS.
3. Re-run the exact failing line, unchanged.

If errno 2 still appears after a clean reset, the name you passed is not a stock name for your firmware build, and you are in cause 2.

Cause 2: the cascade is on your PC and never reached the device

A cascade you trained exists only on the workstation. The camera cannot see the PC's disk, so any path copied out of a training script fails on the device — the file was never there.

Desktop OpenCV hides this: its data files install inside the package and cv2.data.haarcascades points at that folder, so haarcascade_frontalface_default.xml always resolves. An embedded camera has no such folder until you create one and fill it.

Move the file across with the IDE's file-transfer tools, an SD card, or on a controller-class device a plain network copy into a models directory. Verify the copy before you load it:

import os
cascade_path = "/models/frontalface25.cascade"  # illustrative device-side path (str)
print(os.listdir("/models"))  # standard Python: what actually landed on the device
face_cascade = image.HaarCascade(cascade_path, stages=25)

The listing is the test: if the cascade's file name is not in the printed list, the transfer failed, and the loader will raise the same errno 2 — correctly.

Cause 3: the file is there, the path is not

Three spelling-level failures produce the same errno on a healthy copy:

• Case. On-board filesystems are case-sensitive: frontalface and FrontalFace resolve differently.
• Relative paths. A script run from the IDE inherits one working directory; the same script launched at boot usually starts in another, so a relative path opens nothing in one of the two runs.
• Foreign separators. A path pasted from a Windows training machine carries backslashes or a drive letter the device cannot parse.

Deployments that pass in the IDE and fail on the line are almost always the middle case; the model file path deployment fix goes deeper, and the cross-OS path error guide covers the separator side. Print before you load:

import os
print(os.getcwd())                        # where relative paths resolve right now
os.stat("/models/frontalface25.cascade")  # raises errno 2 here, before the loader

If the path was assembled by string concatenation, the escaping traps are the same ones that bite GenTL CTI file paths.

Worked example: error to detection in five minutes

Take the failing call and walk it end to end:

1. Re-run it unchanged and read the message. OSError: [Errno 2] ENOENT confirms a missing file; a corrupt file would get past the open and fail later, at parse time.
2. Look at what you passed. A bare name (frontalface) means a stock ROMFS lookup; anything containing a separator is a path into device storage.
3. Bare name: flash the current firmware, run Tools → ROMFS → Reset ROMFS, re-run. This clears the most common case outright.
4. Path: run the two-line check from cause 3. An errno 2 from the os.stat call pins the failure to the exact path before any model code runs.
5. Copy the file, list the directory, confirm the name in the output, then load again.
6. Only now weigh stages=25: the stage count trades detection speed against recall, and it is read after the file opens.

Capacity is almost never the suspect. On a vision controller such as the MV-VC2140-128G40-1T, with 8 GB memory, a 128 GB SSD and a 1 TB HDD, a whole cascade library amounts to a few megabytes; on an on-device smart camera the constraint is where the file lives, not how much room it takes.

Prevention: make every model path deterministic

• Keep one models directory on the device, referenced by absolute path from every script, IDE run or boot run alike.
• Check existence before the constructor: os.stat the exact path and raise your own error naming it, so a future failure says which file vanished.
• Copy, then verify: after every transfer, list the directory and confirm the file before the line that loads it.
• After any firmware update, re-run Tools → ROMFS → Reset ROMFS so stock names stay present, and re-check any custom files you keep on the board.
• Log the resolved path inside the exception handler instead of the bare errno.
• Keep the deployed model folder under version control, and pin library versions the way SDK version pinning prevents edge inference crashes.

Once the file opens, the classifier itself still has limits of its own; the cascade rotation and scale guide shows what a cascade matched to flat parts will and will not tolerate.

When it is not a path problem at all

• Every open fails, not just the cascade: storage is absent or unmounted, and the fix is the mount, not the path.
• The script never reaches the loader and the camera drops its first frames after power-up: that is the first-images ready-gate fault, a different failure with its own fix.
• Saving results fails with errno 30: you are writing into the read-only ROM filesystem. Captured data belongs in writable storage, as storing images on vision board flash shows for C deployments.

Parts for detection that runs on the device

If the plan is detection on the camera itself, with no PC in the loop, the smart cameras category is built for inspection on the device:

Where several cameras share one model folder and one home, vision controllers give every script a conventional filesystem on their own SSD:

Either way the model and the loader end up on the same filesystem, and the path you print is the path that opens. To size the camera side, filter the camera finder by interface, resolution and lens mount; the systems topic page collects the rest of the on-device debugging guides, and the contact page is the route to a quoted set-up.