{"record":{"id":"150b6de0f5adeee8","repo":"github/copilot-sdk","slug":"copilot-runtime-host-start-failed-library-libr","errorCode":null,"errorMessage":"copilot_runtime_host_start failed (library '{_libraryPath}').","messagePattern":"copilot_runtime_host_start failed \\(library '(.+?)'\\)\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"dotnet/src/FfiRuntimeHost.cs","lineNumber":115,"sourceCode":"        if (OperatingSystem.IsMacOS()) return \"libcopilot_runtime.dylib\";\n        return \"libcopilot_runtime.so\";\n    }\n\n    /// <summary>\n    /// Starts the in-process Rust runtime and opens the FFI JSON-RPC connection.\n    /// </summary>\n    public async Task StartAsync(CancellationToken cancellationToken)\n    {\n        // Keep synchronous native startup off the caller's async context.\n        await Task.Run(() =>\n        {\n            var argvJson = BuildArgvJson(_cliEntrypoint, _args);\n            var envJson = BuildEnvJson(_environment);\n\n            _serverId = NativeHostStart(argvJson, envJson);\n            if (_serverId == 0)\n            {\n                throw new InvalidOperationException(\n                    $\"copilot_runtime_host_start failed (library '{_libraryPath}').\");\n            }\n\n            _connectionId = NativeOpenConnection(_serverId);\n            if (_connectionId == 0)\n            {\n                DisposeNativeCallback();\n                NativeHostShutdown(_serverId);\n                _serverId = 0;\n                throw new InvalidOperationException(\"copilot_runtime_connection_open failed.\");\n            }\n\n            _sendStream = new CallbackSendStream(SendFrame);\n        }, cancellationToken).ConfigureAwait(false);\n\n        if (_logger.IsEnabled(LogLevel.Debug))\n        {\n            _logger.LogDebug(","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/FfiRuntimeHost.cs#L97-L133","documentation":"FfiRuntimeHost.StartAsync calls the native copilot_runtime_host_start entrypoint via P/Invoke. A return value of 0 means the native runtime failed to start its host, so this InvalidOperationException is thrown reporting which library was used, after which no connection can be opened.","triggerScenarios":"NativeHostStart returns 0 — the native library loaded but host initialization failed: invalid argv/env JSON, missing CLI entrypoint, incompatible runtime library version, or the native host failed its own startup (port/socket, permissions, corrupt install).","commonSituations":"Mismatched versions of the managed wrapper and native runtime; cliEntrypoint path wrong so the runtime can't bootstrap; bad environment variables passed through; library built for a different platform and returning failure.","solutions":["Check the native runtime's stderr/logs for the underlying startup failure cause","Verify the native library version matches the managed package version","Confirm cliEntrypoint and args are valid and reachable, and env vars are correct","Test the library standalone (e.g. ldd / otool) to rule out missing native dependencies"],"exampleFix":"// before\nvar host = FfiRuntimeHost.Create(libPath, cliEntrypoint: null, env, args, logger);\nawait host.StartAsync(); // copilot_runtime_host_start failed\n// after\nvar host = FfiRuntimeHost.Create(libPath, cliEntrypoint: \"/usr/local/bin/copilot-cli\", env, args, logger);\ntry { await host.StartAsync(); }\ncatch (InvalidOperationException ex) { logger.LogError(ex, \"FFI host start failed\"); throw; }","handlingStrategy":"try-catch","validationCode":"if (!File.Exists(libPath)) throw new FileNotFoundException(libPath);\n// optionally check native deps: ldd libcopilot_runtime.so (exit code 0)","typeGuard":null,"tryCatchPattern":"try { await host.StartAsync(); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"copilot_runtime_host_start failed\")) { /* log, check native logs/versions, retry with corrected config */ }","preventionTips":["Keep native library and managed wrapper versions in sync","Capture native stderr/logs during startup for the root cause","Validate cliEntrypoint and env config before StartAsync","Smoke-test the native library on the target platform in CI"],"tags":["ffi","native","startup","dotnet"],"backgroundTag":"module-init-failed","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"}