{"record":{"id":"657213512d10b3e6","repo":"deepinsight/insightface","slug":"unsupported-platform-system-system-machine-ma","errorCode":null,"errorMessage":"Unsupported platform: system={system}, machine={machine}","messagePattern":"Unsupported platform: system=(.+?), machine=(.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"cpp-package/inspireface/python/inspireface/modules/core/native.py","lineNumber":75,"sourceCode":"            # Check if running under Rosetta 2\n            try:\n                # Use sysctl to detect Rosetta 2\n                is_rosetta = bool(int(subprocess.check_output(\n                    ['sysctl', '-n', 'sysctl.proc_translated']).decode().strip()))\n                # If running under Rosetta, it's actually an ARM machine\n                if is_rosetta:\n                    arch = 'arm64'\n                else:\n                    arch = 'x64'\n            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:","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/core/native.py#L57-L93","documentation":"Raised by get_lib_path() when the running OS/CPU combination has no mapped platform directory, library name, or architecture in InspireFace's bundled native-library lookup table. The Python package ships prebuilt shared libraries only for supported platforms, and this guard fires before any path is constructed so an unsupported machine fails fast with a clear message instead of a cryptic ctypes load error.","triggerScenarios":"Importing/initializing InspireFace on an OS or machine not covered by the platform mapping (e.g. Windows arm64, 32-bit x86, FreeBSD, or an unusual platform.machine() string like 'aarch64_be'). Any code path that loads the native HF library (first InspireFace call or import of the binding module) reaches get_lib_path().","commonSituations":"Running under an exotic/older interpreter that reports an unrecognized machine string, using Windows-on-ARM, Alpine musl setups, or a wheel that didn't bundle libs for the arch. Also occurs when platform.uname() is mocked or the package was installed from source without the libs directory.","solutions":["Check platform.platform() / platform.machine() output and compare with the mapping in native.py; if your arch string is a synonym (e.g. 'AMD64' vs 'x86_64'), add/normalize it locally or patch get_lib_path","Install a prebuilt wheel matching your OS/arch (x64 or arm64 on Linux/macOS/Windows) rather than building from source","If you're on genuinely unsupported hardware, run InspireFace in a Docker container based on a supported x64 image","Report/patch upstream to extend the platform table for your machine string"],"exampleFix":"import platform\n# before: fails with 'Unsupported platform: system=FreeBSD, machine=amd64'\nsystem, machine = platform.system(), platform.machine()\nassert system in ('Linux','Darwin','Windows') and machine in ('x86_64','arm64','AMD64'), 'need x64/arm64'\n# after: run in an x64 Linux container\ndocker run -it -v $PWD:/w -w /w python:3.10 bash","handlingStrategy":"validation","validationCode":"import platform\ns, m = platform.system(), platform.machine()\nassert s in ('Linux','Darwin','Windows') and m.lower() in ('x86_64','amd64','arm64','aarch64'), f'unsupported: {s}/{m}'","typeGuard":"def is_supported_platform() -> bool:\n    import platform\n    s, m = platform.system(), platform.machine().lower()\n    return s in ('Linux','Darwin','Windows') and m in ('x86_64','amd64','arm64','aarch64')","tryCatchPattern":null,"preventionTips":["Pin to officially supported x64/arm64 base images in Docker","Run CI on supported runners and assert platform before installing inspireface"],"tags":["native-library","platform","architecture","inspireface"],"backgroundTag":"unsupported-platform-architecture","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}