{"record":{"id":"2c209885a1ef130d","repo":"github/copilot-sdk","slug":"ffi-runtime-library-not-found-at-fulllibrarypat","errorCode":null,"errorMessage":"FFI runtime library not found at '${fullLibraryPath}'.","messagePattern":"FFI runtime library not found at '(.+?)'\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"nodejs/src/ffiRuntimeHost.ts","lineNumber":170,"sourceCode":"                } catch (error) {\n                    callback(error as Error);\n                }\n            },\n        });\n    }\n\n    /**\n     * Loads the runtime cdylib at the given path and prepares the FFI host.\n     */\n    static create(\n        libraryPath: string,\n        cliEntrypoint: string | undefined,\n        environment: Record<string, string | undefined> | undefined,\n        args: readonly string[]\n    ): FfiRuntimeHost {\n        const fullLibraryPath = resolve(libraryPath);\n        if (!existsSync(fullLibraryPath)) {\n            throw new Error(`FFI runtime library not found at '${fullLibraryPath}'.`);\n        }\n        return new FfiRuntimeHost(\n            fullLibraryPath,\n            cliEntrypoint ? resolve(cliEntrypoint) : undefined,\n            environment,\n            args\n        );\n    }\n\n    /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */\n    async start(): Promise<void> {\n        const argvJson = buildArgvJson(this.cliEntrypoint, this.args);\n        const envJson = buildEnvJson(this.environment);\n\n        // The native host has no cwd parameter, so it uses this process's cwd. A custom\n        // working directory is intentionally\n        // unsupported for the in-process transport (rejected by the client constructor)\n        // rather than mutating the shared process-global cwd here.","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/nodejs/src/ffiRuntimeHost.ts#L152-L188","documentation":"FfiRuntimeHost.create resolves the given library path and checks existsSync before binding; if the native runtime cdylib is not present at the resolved absolute path, it throws. This is a pre-flight check so failures surface early with a clear path instead of an obscure dlopen error.","triggerScenarios":"Calling FfiRuntimeHost.create with a libraryPath that does not exist relative to the current working directory, the native library not being built/installed, or targeting a platform/arch where the artifact was never produced.","commonSituations":"Forgetting to run the cargo/build step that produces the .so/.dylib/.dll; running the app from a different working directory so a relative path resolves elsewhere; CI containers missing the native artifact; path typos or wrong platform binary.","solutions":["Build/install the native runtime library and verify it exists at the path (ls the resolved fullLibraryPath).","Pass an absolute libraryPath instead of one dependent on process.cwd().","Ensure CI/deployment packages include the correct platform-specific binary.","Fix the path typo / select the artifact matching the current OS and architecture."],"exampleFix":"// before\nFfiRuntimeHost.create('./target/release/runtime.so', ...); // file not built\n// after\nFfiRuntimeHost.create('/abs/path/target/release/libcopilot_runtime.so', ...); // after cargo build --release","handlingStrategy":"validation","validationCode":"import { resolve } from 'node:path';\nimport { existsSync } from 'node:fs';\nconst full = resolve(libPath);\nif (!existsSync(full)) throw new Error(`Runtime library missing: ${full} — build it (e.g. cargo build --release)`);","typeGuard":null,"tryCatchPattern":"let host;\ntry {\n  host = FfiRuntimeHost.create(libPath, cli, env, args);\n} catch (e) {\n  if (String(e.message).includes('not found at')) {\n    console.error(`Build the native library or fix libraryPath. Tried: ${e.message}`);\n  }\n  throw e;\n}","preventionTips":["Run the native build step before starting the app (prebuild/postinstall script)","Use absolute paths resolved from import.meta.url, not process.cwd()-relative ones","Include platform-specific binaries in CI/deployment artifacts","Verify the artifact exists for the current OS/arch in smoke tests"],"tags":["ffi","file-not-found","native-library","deployment"],"backgroundTag":"file-not-found","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"}