What causes "Missing libffi target header: {ffitarget_src}" in nodejs/node?

Run a clean checkout / `git submodule update --init --recursive` for deps/libffi so src/ /ffitarget.h is present.

nodejs/node · error · FileNotFoundError

Missing libffi target header: {ffitarget_src}

Error message

Missing libffi target header: {ffitarget_src}

What it means

After get_target() returns a (target_define, target_dir) pair, generate_headers() looks for deps/libffi/src/<target_dir>/ffitarget.h and copies it into the output directory. If that specific header file is missing from the source tree, it raises FileNotFoundError before writing any header, so the build fails fast rather than emitting an empty ffitarget.h.

Source

Thrown at deps/libffi/generate-headers.py:194

        '#endif',
        '#endif',
        '',
        '#endif  /* LIBFFI_FFICONFIG_H_ */',
        '',
    ])

    return '\n'.join(lines)


def generate_headers(output_dir, target_arch, os_name):
    base_dir = Path(__file__).resolve().parent
    output_dir = Path(str(output_dir).strip().strip('"'))
    output_dir.mkdir(parents=True, exist_ok=True)

    target, target_dir = get_target(os_name, target_arch)
    ffitarget_src = base_dir / 'src' / target_dir / 'ffitarget.h'
    if not ffitarget_src.exists():
        raise FileNotFoundError(f'Missing libffi target header: {ffitarget_src}')

    (output_dir / 'ffi.h').write_text(
        render_ffi_header(base_dir, os_name, target_arch, target),
        encoding='utf-8')
    (output_dir / 'fficonfig.h').write_text(
        render_fficonfig(os_name, target_arch),
        encoding='utf-8')
    (output_dir / 'ffitarget.h').write_text(
        ffitarget_src.read_text(encoding='utf-8'),
        encoding='utf-8')


def detect_os_name():
    if sys.platform.startswith('win'):
        return 'win'
    if sys.platform == 'darwin':
        return 'mac'
    if sys.platform.startswith('linux'):

View on GitHub (pinned to 1b2de5e052)

Solutions

Run a clean checkout / `git submodule update --init --recursive` for deps/libffi so src/<arch>/ffitarget.h is present.
Verify the target_dir returned by get_target() actually has a directory under deps/libffi/src/.
If the header genuinely isn't shipped for your target, add it upstream or switch to a supported target.

Example fix

# before: shallow checkout missing src/aarch64/ffitarget.h
python generate-headers.py --output-dir out --target-arch arm64
# after
git -C deps/libffi fetch --unshallow && git -C deps/libffi checkout origin/main -- src/aarch64
python generate-headers.py --output-dir out --target-arch arm64

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path
h = Path('deps/libffi/src') / target_dir / 'ffitarget.h'
assert h.exists(), f'missing ffitarget header {h}; run a full checkout of deps/libffi'

Prevention

Use `git submodule update --init --recursive` (or the project's fetch script) so arch-specific headers are present.
Add a CI step that asserts expected ffitarget.h files exist before building.

When it happens

Trigger: Raised when `ffitarget_src = base_dir / 'src' / target_dir / 'ffitarget.h'` does not exist on disk. target_dir comes from get_target(), so this fires when the directory mapping is known but the header file itself was deleted, not vendored, or sits behind a git-lfs/submodule that wasn't fetched.

Common situations: Shallow or partial git checkout of deps/libffi that omitted src/<arch>/; a subtree split or vendor script that dropped architecture-specific headers; a forked libffi that renamed target directories without updating get_target().

Related errors

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/c3358ed760e2e504. Report an issue: GitHub.