deepinsight/insightface · critical · RuntimeError

Unsupported platform: system={system}, machine={machine}

Error message

Unsupported platform: system={system}, machine={machine}

What it means

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.

Source

Thrown at cpp-package/inspireface/python/inspireface/modules/core/native.py:75

            # Check if running under Rosetta 2
            try:
                # Use sysctl to detect Rosetta 2
                is_rosetta = bool(int(subprocess.check_output(
                    ['sysctl', '-n', 'sysctl.proc_translated']).decode().strip()))
                # If running under Rosetta, it's actually an ARM machine
                if is_rosetta:
                    arch = 'arm64'
                else:
                    arch = 'x64'
            except:
                # If detection fails, assume native x64
                arch = 'x64'
        elif machine == 'arm64':
            arch = 'arm64'
            
    # Validate that all necessary parameters were set
    if not all([platform_dir, lib_name, arch]):
        raise RuntimeError(
            f"Unsupported platform: system={system}, machine={machine}")
    
    # Construct the full library path
    dir_path = package_dir / 'libs' / platform_dir / arch
    os.makedirs(dir_path, exist_ok=True)
    lib_path = dir_path / lib_name
    
    # Verify that the library file exists
    if not lib_path.exists():
        raise RuntimeError(
            f"Library not found at {lib_path}. "
            f"System: {system}, Architecture: {arch}")
    
    return str(lib_path)

try:    
    _LIBRARY_FILENAME = get_lib_path()
except Exception as e:

View on GitHub (pinned to 7fadd420c2)

Solutions

1. 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
2. Install a prebuilt wheel matching your OS/arch (x64 or arm64 on Linux/macOS/Windows) rather than building from source
3. If you're on genuinely unsupported hardware, run InspireFace in a Docker container based on a supported x64 image
4. Report/patch upstream to extend the platform table for your machine string

Example fix

import platform
# before: fails with 'Unsupported platform: system=FreeBSD, machine=amd64'
system, machine = platform.system(), platform.machine()
assert system in ('Linux','Darwin','Windows') and machine in ('x86_64','arm64','AMD64'), 'need x64/arm64'
# after: run in an x64 Linux container
docker run -it -v $PWD:/w -w /w python:3.10 bash

import platform
s, m = platform.system(), platform.machine()
assert s in ('Linux','Darwin','Windows') and m.lower() in ('x86_64','amd64','arm64','aarch64'), f'unsupported: {s}/{m}'

def is_supported_platform() -> bool:
    import platform
    s, m = platform.system(), platform.machine().lower()
    return s in ('Linux','Darwin','Windows') and m in ('x86_64','amd64','arm64','aarch64')

When it happens

Trigger: 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().

Common situations: 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.

Related errors

• Library not found at {lib_path}. System: {system}, Architect
• Unknown calling convention '{}' for function '{}'
• Could not load %s.
• HERR_INVALID_PARAM
• HERR_INVALID_FACE_FEATURE

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/657213512d10b3e6. Report an issue: GitHub.