heygen-com/hyperframes · critical · Error

[build-zip] ${label} at ${path} is not a Linux x86-64 ELF ex

Error message

[build-zip] ${label} at ${path} is not a Linux x86-64 ELF executable (magic=0x${magicHex}, ei_class=${head[4]}, e_machine=0x${machine.toString(16)}). This usually means the deploy host's postinstall fetched a host-platform binary (e.g. macOS arm64 ffmpeg) instead of the linux/x64 binary Lambda needs. Re-run the build inside a linux/amd64 container, or pre-install with `npm_config_platform=linux npm_config_arch=x64` so the package fetches the right binary.

What it means

assertLinuxX86_64Elf reads the first bytes of a binary and verifies the ELF magic (7f 45 4c 46), ELFCLASS64 (byte 4 equals 2), and e_machine equals EM_X86_64 (0x3E at offset 18). If any check fails it throws, because Lambda runs Linux x86-64 and a host-platform binary (e.g., macOS arm64 Mach-O) would deploy but crash at runtime with 'cannot execute binary file'.

Source

Thrown at packages/aws-lambda/scripts/build-zip.ts:369

const ELF_MACHINE_X86_64 = 0x3e;
const ELF_HEADER_BYTES = 20;

/**
 * Verify the binary at `path` is a Linux x86-64 ELF executable, the only
 * shape the Lambda runtime can exec. Throws with the canonical workaround
 * (Docker `--platform=linux/amd64` or `npm_config_platform` /
 * `npm_config_arch` overrides) so the build doesn't ship a silently
 * broken zip when a non-Linux host's postinstall fetched the wrong arch.
 */
function assertLinuxX86_64Elf(path: string, label: string): void {
  const head = readFileHead(path, ELF_HEADER_BYTES, label);
  const isElf = head.subarray(0, 4).equals(ELF_MAGIC);
  const isElf64 = head[4] === ELF_CLASS_64;
  const machine = head.readUInt16LE(18);
  if (isElf && isElf64 && machine === ELF_MACHINE_X86_64) return;

  const magicHex = head.subarray(0, 4).toString("hex");
  throw new Error(
    `[build-zip] ${label} at ${path} is not a Linux x86-64 ELF executable ` +
      `(magic=0x${magicHex}, ei_class=${head[4]}, e_machine=0x${machine.toString(16)}). ` +
      `This usually means the deploy host's postinstall fetched a host-platform binary ` +
      `(e.g. macOS arm64 ffmpeg) instead of the linux/x64 binary Lambda needs. ` +
      `Re-run the build inside a linux/amd64 container, or pre-install with ` +
      `\`npm_config_platform=linux npm_config_arch=x64\` so the package fetches the right binary.`,
  );
}

function readFileHead(path: string, byteCount: number, label: string): Buffer {
  const fd = openSync(path, "r");
  try {
    const buf = Buffer.alloc(byteCount);
    const bytesRead = readSync(fd, buf, 0, byteCount, 0);
    if (bytesRead < byteCount) {
      throw new Error(
        `[build-zip] ${label} at ${path} is too short — read ${bytesRead} of ${byteCount} bytes.`,
      );

View on GitHub (pinned to c2996c8626)

Solutions

Build inside a linux/amd64 Docker container: docker run --platform=linux/amd64.
Set npm_config_platform=linux and npm_config_arch=x64 before installing so packages fetch linux/x64 binaries.
Use CI runners with linux/amd64 architecture.

Example fix

// before (on macOS)
tsx packages/aws-lambda/scripts/build-zip.ts

// after
docker run --platform=linux/amd64 --rm -v "$PWD":/work -w /work node:20 \
  tsx packages/aws-lambda/scripts/build-zip.ts

Defensive patterns

Strategy: validation

Validate before calling

import { platform, arch } from "node:os";
if (platform() !== "linux" || arch() !== "x64") {
  console.error(
    `Build host is ${platform()}/${arch()}, but Lambda needs linux/x64 binaries. ` +
    `Build inside a linux/amd64 container or set npm_config_platform=linux npm_config_arch=x64.`,
  );
  process.exit(1);
}

Prevention

Build the Lambda zip exclusively in a linux/amd64 environment.
Set npm_config_platform=linux and npm_config_arch=x64 before install if building on another platform.
Add a platform check at the start of the CI build job.

When it happens

Trigger: Building the Lambda zip on a non-Linux-x64 host (macOS, Windows, or Linux arm64). The ffmpeg-static, ffprobe-static, or chrome-headless-shell postinstall fetched a binary for the build host's platform instead of the linux/x64 binary Lambda needs.

Common situations: Developer building directly on macOS (Apple Silicon or Intel); CI runner that is not linux/amd64; building on a Linux arm64 machine.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/55edabc06fa81449. Report an issue: GitHub.