github/copilot-sdk · critical

FFI runtime library not found at

Error message

FFI runtime library not found at '${fullLibraryPath}'.

What it means

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.

Solutions

1. Build/install the native runtime library and verify it exists at the path (ls the resolved fullLibraryPath).
2. Pass an absolute libraryPath instead of one dependent on process.cwd().
3. Ensure CI/deployment packages include the correct platform-specific binary.
4. Fix the path typo / select the artifact matching the current OS and architecture.

Example fix

// before
FfiRuntimeHost.create('./target/release/runtime.so', ...); // file not built
// after
FfiRuntimeHost.create('/abs/path/target/release/libcopilot_runtime.so', ...); // after cargo build --release

import { resolve } from 'node:path';
import { existsSync } from 'node:fs';
const full = resolve(libPath);
if (!existsSync(full)) throw new Error(`Runtime library missing: ${full} — build it (e.g. cargo build --release)`);

let host;
try {
  host = FfiRuntimeHost.create(libPath, cli, env, args);
} catch (e) {
  if (String(e.message).includes('not found at')) {
    console.error(`Build the native library or fix libraryPath. Tried: ${e.message}`);
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• In-process FFI runtime library not found at
• An in-process FFI runtime library is already loaded from
• copilot_runtime_host_start failed
• copilot_runtime_connection_open failed.
• FFI runtime library not found. Looked for

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

Appendix: source

Thrown at nodejs/src/ffiRuntimeHost.ts:170

                } catch (error) {
                    callback(error as Error);
                }
            },
        });
    }

    /**
     * Loads the runtime cdylib at the given path and prepares the FFI host.
     */
    static create(
        libraryPath: string,
        cliEntrypoint: string | undefined,
        environment: Record<string, string | undefined> | undefined,
        args: readonly string[]
    ): FfiRuntimeHost {
        const fullLibraryPath = resolve(libraryPath);
        if (!existsSync(fullLibraryPath)) {
            throw new Error(`FFI runtime library not found at '${fullLibraryPath}'.`);
        }
        return new FfiRuntimeHost(
            fullLibraryPath,
            cliEntrypoint ? resolve(cliEntrypoint) : undefined,
            environment,
            args
        );
    }

    /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */
    async start(): Promise<void> {
        const argvJson = buildArgvJson(this.cliEntrypoint, this.args);
        const envJson = buildEnvJson(this.environment);

        // The native host has no cwd parameter, so it uses this process's cwd. A custom
        // working directory is intentionally
        // unsupported for the in-process transport (rejected by the client constructor)
        // rather than mutating the shared process-global cwd here.

View on GitHub (pinned to cd8cf15dc3)