{"record":{"id":"25e23e419ee4f998","repo":"deepinsight/insightface","slug":"the-rec-addmaskparam-command-requires-optional-mas","errorCode":null,"errorMessage":"The rec.addmaskparam command requires optional mask rendering and MXNet record dependencies. Please install the required optional dependencies before running this command.","messagePattern":"The rec\\.addmaskparam command requires optional mask rendering and MXNet record dependencies\\. Please install the required optional dependencies before running this command\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/commands/rec_add_mask_param.py","lineNumber":47,"sourceCode":"        output: str,\n    ):\n        self._input = input\n        self._output = output\n\n\n    def run(self):\n        try:\n            import mxnet as mx\n        except ImportError as exc:\n            raise ImportError(\n                \"The rec.addmaskparam command requires mxnet. \"\n                \"Please install mxnet before running this command.\"\n            ) from exc\n        try:\n            from ..app.mask_renderer import MaskRenderer\n            from ..data.rec_builder import RecBuilder\n        except ImportError as exc:\n            raise ImportError(\n                \"The rec.addmaskparam command requires optional mask rendering \"\n                \"and MXNet record dependencies. Please install the required \"\n                \"optional dependencies before running this command.\"\n            ) from exc\n\n        tool = MaskRenderer()\n        tool.prepare(ctx_id=0, det_size=(128,128))\n        root_dir = self._input\n        path_imgrec = os.path.join(root_dir, 'train.rec')\n        path_imgidx = os.path.join(root_dir, 'train.idx')\n        imgrec = mx.recordio.MXIndexedRecordIO(path_imgidx, path_imgrec, 'r')\n        save_path = self._output\n        wrec=RecBuilder(path=save_path)\n        s = imgrec.read_idx(0)\n        header, _ = mx.recordio.unpack(s)\n        if header.flag > 0:\n            if len(header.label)==2:\n                imgidx = np.array(range(1, int(header.label[0])))","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/commands/rec_add_mask_param.py#L29-L65","documentation":"The second guard in rec.addmaskparam.run(): mxnet imports fine, but importing insightface's optional mask-rendering modules (..app.mask_renderer.MaskRenderer, ..data.rec_builder.RecBuilder) fails, so the command re-raises ImportError citing optional dependencies. The optional mask-rendering stack is present in name but its transitive deps are missing or incompatible.","triggerScenarios":"Running rec.addmaskparam where 'import mxnet' succeeds but 'from ..app.mask_renderer import MaskRenderer' or 'from ..data.rec_builder import RecBuilder' raises ImportError — missing opencv-contrib, mxnet version incompatible with the record IO code, or a partial insightface install.","commonSituations":"Installing insightface without training extras; mxnet 2.x vs 1.x API mismatch in rec_builder; cv2 import failing due to missing system libs; numpy 2.x breaking old mxnet/record tooling.","solutions":["Run 'python -c \"from insightface.app.mask_renderer import MaskRenderer; from insightface.data.rec_builder import RecBuilder\"' to surface the underlying missing module and install it.","Pin compatible versions: mxnet<2.0, opencv-contrib-python, numpy<2.","Reinstall insightface from source so all bundled submodules are present: pip install -e .","Run the command in the legacy Python 3.8 container recommended for insightface training tools."],"exampleFix":"# before\ninsightface rec.addmaskparam ...  # ImportError: requires optional mask rendering and MXNet record dependencies\n\n# after\npip install opencv-contrib-python 'mxnet<2.0' 'numpy<2'\ninsightface rec.addmaskparam ...","handlingStrategy":"validation","validationCode":"try:\n    from insightface.app.mask_renderer import MaskRenderer\n    from insightface.data.rec_builder import RecBuilder\n    ok = True\nexcept ImportError:\n    ok = False\nassert ok, 'install optional deps: opencv-contrib-python \"mxnet<2.0\" \"numpy<2\"'","typeGuard":null,"tryCatchPattern":"try:\n    from insightface.app.mask_renderer import MaskRenderer\nexcept ImportError as e:\n    raise RuntimeError(f'mask-rendering extras missing ({e}); pip install opencv-contrib-python \"mxnet<2.0\"') from e","preventionTips":["Install the full training-extras set in one pinned requirements file.","Smoke-test optional imports at startup with an actionable message."],"tags":["optional-dependency","mxnet","import","cli","mask"],"backgroundTag":"missing-optional-dependency","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}