{"record":{"id":"b908a78044df4fba","repo":"nodejs/node","slug":"unable-to-determine-target-architecture-for-libffi","errorCode":null,"errorMessage":"Unable to determine target architecture for libffi headers","messagePattern":"Unable to determine target architecture for libffi headers","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"deps/libffi/generate-headers.py","lineNumber":256,"sourceCode":"        'arm64': 'arm64',\n        'aarch64': 'arm64',\n        'arm': 'arm',\n        'riscv64': 'riscv64',\n        'loong64': 'loong64',\n        'ppc64': 'ppc64',\n        'mips': 'mips',\n        'mipsel': 'mipsel',\n        'mips64el': 'mips64el',\n    }\n\n    for candidate in candidates:\n        if not candidate:\n            continue\n        normalized = aliases.get(candidate.lower())\n        if normalized is not None:\n            return normalized\n\n    raise ValueError('Unable to determine target architecture for libffi headers')\n\n\ndef main(argv=None):\n    parser = argparse.ArgumentParser(description='Generate libffi headers')\n    parser.add_argument('--output-dir', required=True)\n    parser.add_argument('--target-arch')\n    parser.add_argument('--os')\n    args = parser.parse_args(argv)\n\n    try:\n        generate_headers(args.output_dir,\n                         args.target_arch or detect_target_arch(),\n                         args.os or detect_os_name())\n    except Exception as exc:  # pylint: disable=broad-except\n        print(exc, file=sys.stderr)\n        return 1\n\n    return 0","sourceCodeStart":238,"sourceCodeEnd":274,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/libffi/generate-headers.py#L238-L274","documentation":"detect_target_arch() walks a candidate list (TARGET_ARCH, npm_config_arch, VSCMD_ARG_TGT_ARCH, Platform, PROCESSOR_ARCHITECTURE, platform.machine()) and normalizes each through an aliases map. If none of the candidates map to a known architecture key, it can't decide which ffitarget to generate and aborts.","triggerScenarios":"Raised when every candidate env var is unset/empty and platform.machine() returns something not in the aliases dict (e.g. 'aarch64' if unaliased, 'riscv64', 'ppc64le' spelled differently). Only fires when --target-arch is not given on the CLI.","commonSituations":"Cross-compile shells where TARGET_ARCH/npm_config_arch are unset and platform.machine() reports an unrecognized string; building on arches whose platform.machine() spelling differs from the aliases keys; CI images that don't set npm_config_arch.","solutions":["Pass --target-arch explicitly with a recognized value (x86, x86_64, arm, arm64, mips, ...).","Set TARGET_ARCH (or npm_config_arch) in the build environment to a value present in the aliases map.","If your arch is legitimately supported upstream, add the missing alias in detect_target_arch()."],"exampleFix":"# before: platform.machine()='riscv64' unknown, no env set\npython generate-headers.py --output-dir out\n# after\npython generate-headers.py --output-dir out --target-arch x86_64","handlingStrategy":"validation","validationCode":"import os, platform\nALIASES = {'x64':'x86_64','amd64':'x86_64','x86':'x86','ia32':'x86',\n           'arm':'arm','arm64':'arm64','aarch64':'arm64','mips':'mips'}\nfor cand in (os.environ.get('TARGET_ARCH'), os.environ.get('npm_config_arch'), platform.machine()):\n    if cand and cand.lower() in ALIASES:\n        arch = ALIASES[cand.lower()]; break\nelse:\n    raise SystemExit('set --target-arch or TARGET_ARCH to a recognized value')","typeGuard":"def recognized_arch(value):\n    aliases = {'x64':'x86_64','amd64':'x86_64','x86':'x86','arm':'arm','arm64':'arm64','aarch64':'arm64','mips':'mips'}\n    return value is not None and value.lower() in aliases","tryCatchPattern":null,"preventionTips":["Always pass --target-arch in cross-compile builds rather than relying on platform.machine().","Set npm_config_arch in CI for native modules embedding libffi."],"tags":["libffi","build","ffi","cross-compile","arch-detect"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}