{"record":{"id":"05256edd4eb7d3b3","repo":"deepinsight/insightface","slug":"library-not-found-at-lib-path-system-system","errorCode":null,"errorMessage":"Library not found at {lib_path}. System: {system}, Architecture: {arch}","messagePattern":"Library not found at (.+?)\\. System: (.+?), Architecture: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"cpp-package/inspireface/python/inspireface/modules/core/native.py","lineNumber":85,"sourceCode":"            except:\n                # If detection fails, assume native x64\n                arch = 'x64'\n        elif machine == 'arm64':\n            arch = 'arm64'\n            \n    # Validate that all necessary parameters were set\n    if not all([platform_dir, lib_name, arch]):\n        raise RuntimeError(\n            f\"Unsupported platform: system={system}, machine={machine}\")\n    \n    # Construct the full library path\n    dir_path = package_dir / 'libs' / platform_dir / arch\n    os.makedirs(dir_path, exist_ok=True)\n    lib_path = dir_path / lib_name\n    \n    # Verify that the library file exists\n    if not lib_path.exists():\n        raise RuntimeError(\n            f\"Library not found at {lib_path}. \"\n            f\"System: {system}, Architecture: {arch}\")\n    \n    return str(lib_path)\n\ntry:    \n    _LIBRARY_FILENAME = get_lib_path()\nexcept Exception as e:\n    print(e)\n\n_int_types = (ctypes.c_int16, ctypes.c_int32)\nif hasattr(ctypes, \"c_int64\"):\n    # Some builds of ctypes apparently do not have ctypes.c_int64\n    # defined; it's a pretty good bet that these builds do not\n    # have 64-bit pointers.\n    _int_types += (ctypes.c_int64,)\nfor t in _int_types:\n    if ctypes.sizeof(t) == ctypes.sizeof(ctypes.c_size_t):","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/core/native.py#L67-L103","documentation":"get_lib_path() computed the expected install location for the InspireFace native shared library (package_dir/libs/<platform>/<arch>/<lib_name>) and verified it exists, but the file is missing. The directory is even created with makedirs, so the error specifically means the binary payload was never shipped/downloaded into the Python package.","triggerScenarios":"First use of InspireFace after a pip install from source (no bundled libs), a partially corrupted wheel install, manually deleting the libs directory, or a packaging bug where the .so/.dll/.dylib was excluded (e.g. slim docker image, .gitignore applied during packaging).","commonSituations":"pip install from a git clone instead of the release wheel; docker multi-stage builds that strip binaries; antivirus quarantining the DLL on Windows; upgrading the package with --no-cache-dir leaving stale files; CI caching a broken site-packages.","solutions":["Reinstall cleanly: pip uninstall inspireface && pip install inspireface --force-reinstall","Verify the file: ls <site-packages>/inspireface/libs/<platform>/<arch>/ and confirm the expected library name exists","If installing from source, build the C++ package first so the libs are copied into python/inspireface/libs","On Windows, check antivirus/quarantine and restore or whitelist the DLL"],"exampleFix":"# before: RuntimeError: Library not found at .../libs/linux/x64/libinspireface.so\npip uninstall -y inspireface\n# after\npip install --force-reinstall --no-cache-dir inspireface\npython -c \"import inspireface; print('ok')\"","handlingStrategy":"validation","validationCode":"import inspireface, pathlib\np = pathlib.Path(inspireface.__file__).parent / 'libs'\nassert any(p.rglob('libinspireface*')) or any(p.rglob('InspireFace*')), 'native libs missing — reinstall'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install from official release wheels, not source clones, unless you build the C++ libs","Add a smoke test (import inspireface) to Docker builds to catch stripped/broken installs"],"tags":["native-library","missing-file","installation","inspireface"],"backgroundTag":"missing-native-library","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}