{"record":{"id":"7d4be339587704e8","repo":"github/copilot-sdk","slug":"unsupported-architecture-arch-for-in-process","errorCode":null,"errorMessage":"Unsupported architecture '${arch}' for in-process FFI hosting.","messagePattern":"Unsupported architecture '(.+?)' for in-process FFI hosting\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nodejs/src/client.ts","lineNumber":2873,"sourceCode":"     */\n    private async connectViaFfi(): Promise<void> {\n        if (!this.ffiHost) {\n            throw new Error(\"In-process FFI runtime host not started\");\n        }\n        this.messageWriter = new TeardownResilientStreamMessageWriter(this.ffiHost.sendStream);\n        this.connection = createMessageConnection(\n            new StreamMessageReader(this.ffiHost.receiveStream),\n            this.messageWriter\n        );\n\n        this.attachConnectionHandlers();\n        this.connection.listen();\n    }\n\n    private static getNapiPrebuildsFolder(entrypoint: string): string {\n        const arch = process.arch;\n        if (arch !== \"x64\" && arch !== \"arm64\") {\n            throw new Error(`Unsupported architecture '${arch}' for in-process FFI hosting.`);\n        }\n        let platform: string = process.platform;\n        if (platform === \"linux\" && CopilotClient.isMusl(entrypoint)) {\n            platform = \"linuxmusl\";\n        }\n        return `${platform}-${arch}`;\n    }\n\n    private static isMusl(entrypoint: string): boolean {\n        if (entrypoint.includes(`copilot-linuxmusl-${process.arch}`)) {\n            return true;\n        }\n        if (entrypoint.includes(`copilot-linux-${process.arch}`)) {\n            return false;\n        }\n        const report = process.report?.getReport();\n        const header =\n            report && \"header\" in report","sourceCodeStart":2855,"sourceCodeEnd":2891,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/client.ts#L2855-L2891","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run on an x64 or arm64 machine or container image (e.g. use a linux/amd64 or linux/arm64 Docker base image).","Install a 64-bit Node.js build matching the host CPU (x64 or arm64) instead of a 32-bit or exotic-arch build.","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.","If you must support another architecture, build the native addon from source and/or file an upstream request for that prebuild target."],"exampleFix":"// before (32-bit Node on CI)\n// uses node:20-slim variant that resolved to i386\nnew CopilotClient({ ... });\n\n// after\n// pin 64-bit image\nFROM node:20-bookworm (amd64/arm64)\nnew CopilotClient({ ... });","handlingStrategy":"validation","validationCode":"const SUPPORTED = new Set(['x64', 'arm64']);\nif (!SUPPORTED.has(process.arch)) {\n  throw new Error(`In-process FFI hosting requires x64/arm64, got ${process.arch}`);\n}","typeGuard":"const isSupportedArch = (a: string): a is 'x64' | 'arm64' => a === 'x64' || a === 'arm64';","tryCatchPattern":"try {\n  client = new CopilotClient({ ... });\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Unsupported architecture')) {\n    // fall back to child-process hosting or fail fast with a clear setup message\n  }\n  throw err;\n}","preventionTips":["Pin CI/Docker images to amd64 or arm64 platforms explicitly.","Always install 64-bit Node.js builds on x64/arm64 hardware.","Check process.arch at app startup and choose the hosting mode accordingly.","Document supported architectures where users configure deployment targets."],"tags":["architecture","ffi","platform-support","napi"],"backgroundTag":"unsupported-platform","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}