The dictionary used to print the marker must match the dictionary used to detect it.
What the message means
Each dictionary has its own patterns. A marker from one will not be found by another. Small, blurred or glossy markers also fail.
Fix it in this order
- Print the marker from the dictionary you pass to the detector.
- Keep a white border around it, and print on matte paper.
- Make the marker large enough that it covers many pixels in the image.
- Focus the camera and light the marker evenly.
- Check the library version, since the detector interface changed between OpenCV versions.
- Calibrate the camera for pose estimation.
Why it happens
An ArUco dictionary is a fixed set of bit patterns, named by its grid size and how many markers it holds, such as 4×4 with 50 markers. A marker only matches in the dictionary it came from, and an ID higher than the dictionary holds does not exist. The detector also needs a white border around the marker to find its edges.
OpenCV 4.7 changed the Python interface to an ArucoDetector class, so older tutorials fail with attribute errors on newer installs. Print the marker large and matte, since glare removes the black and white contrast the detector depends on.
If you see this, do this
| You see | Do this |
|---|---|
| Never detected | Dictionary mismatch. |
| Detected only close up | Marker too small or blurred. |
Related
ArUco localization, camera calibration.
Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.