github/copilot-sdk · error

Unsupported architecture

Error message

Unsupported architecture '${arch}' for in-process FFI hosting.

What it means

CopilotClient's in-process FFI hosting mode loads a native N-API prebuilt binary, which is only compiled for x64 and arm64 architectures. If process.arch is anything else (e.g. ia32, arm, ppc64, s390x, riscv64), the client throws immediately rather than attempting to load a nonexistent prebuild. This is a hard platform-support guard, not a runtime failure.

Solutions

1. Run on an x64 or arm64 machine or container image (e.g. use a linux/amd64 or linux/arm64 Docker base image).
2. Install a 64-bit Node.js build matching the host CPU (x64 or arm64) instead of a 32-bit or exotic-arch build.
3. Switch the client to a hosting mode that does not require native prebuilds, such as spawning the CLI as a child process over stdio/TCP.
4. If you must support another architecture, build the native addon from source and/or file an upstream request for that prebuild target.

Example fix

// before (32-bit Node on CI)
// uses node:20-slim variant that resolved to i386
new CopilotClient({ ... });

// after
// pin 64-bit image
FROM node:20-bookworm (amd64/arm64)
new CopilotClient({ ... });

const SUPPORTED = new Set(['x64', 'arm64']);
if (!SUPPORTED.has(process.arch)) {
  throw new Error(`In-process FFI hosting requires x64/arm64, got ${process.arch}`);
}

const isSupportedArch = (a: string): a is 'x64' | 'arm64' => a === 'x64' || a === 'arm64';

try {
  client = new CopilotClient({ ... });
} catch (err) {
  if (err instanceof Error && err.message.includes('Unsupported architecture')) {
    // fall back to child-process hosting or fail fast with a clear setup message
  }
  throw err;
}

When it happens

Trigger: Constructing CopilotClient with in-process FFI hosting on a machine whose process.arch is not 'x64' or 'arm64' — e.g. running Node.js 32-bit builds on Windows, linux/armv7 single-board computers, or big-endian ppc64/s390x hosts.

Common situations: Running in Docker containers built for non-amd64/arm64 platforms (armv7 Raspberry Pi, s390x mainframe CI), using a 32-bit Node distribution on a 64-bit OS, or emulated/QEMU architectures in CI matrices.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• An in-process FFI runtime library is already loaded from
• FFI runtime library not found at
• copilot_runtime_host_start failed
• copilot_runtime_connection_open failed.
• The in-process runtime connection is closed.

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/7d4be339587704e8. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/client.ts:2873

     */
    private async connectViaFfi(): Promise<void> {
        if (!this.ffiHost) {
            throw new Error("In-process FFI runtime host not started");
        }
        this.messageWriter = new TeardownResilientStreamMessageWriter(this.ffiHost.sendStream);
        this.connection = createMessageConnection(
            new StreamMessageReader(this.ffiHost.receiveStream),
            this.messageWriter
        );

        this.attachConnectionHandlers();
        this.connection.listen();
    }

    private static getNapiPrebuildsFolder(entrypoint: string): string {
        const arch = process.arch;
        if (arch !== "x64" && arch !== "arm64") {
            throw new Error(`Unsupported architecture '${arch}' for in-process FFI hosting.`);
        }
        let platform: string = process.platform;
        if (platform === "linux" && CopilotClient.isMusl(entrypoint)) {
            platform = "linuxmusl";
        }
        return `${platform}-${arch}`;
    }

    private static isMusl(entrypoint: string): boolean {
        if (entrypoint.includes(`copilot-linuxmusl-${process.arch}`)) {
            return true;
        }
        if (entrypoint.includes(`copilot-linux-${process.arch}`)) {
            return false;
        }
        const report = process.report?.getReport();
        const header =
            report && "header" in report

View on GitHub (pinned to cd8cf15dc3)