{"record":{"id":"24f9d01913bff3e2","repo":"github/copilot-sdk","slug":"copilot-runtime-connection-open-failed-24f9d0","errorCode":null,"errorMessage":"copilot_runtime_connection_open failed.","messagePattern":"copilot_runtime_connection_open failed\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"dotnet/src/FfiRuntimeHost.cs","lineNumber":125,"sourceCode":"        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(\n                \"FfiRuntimeHost started. Library={Library}, ServerId={ServerId}, ConnectionId={ConnectionId}\",\n                _libraryPath, _serverId, _connectionId);\n        }\n    }\n\n    private static byte[] BuildArgvJson(string? cliEntrypoint, IReadOnlyList<string> args)\n    {\n        using var stream = new MemoryStream();\n        using (var writer = new Utf8JsonWriter(stream))\n        {","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/FfiRuntimeHost.cs#L107-L143","documentation":"Thrown by FfiRuntimeHost.StartAsync when the native call copilot_runtime_connection_open returns a null handle (0), meaning the in-process FFI runtime could not open a connection for this server. The host cleans up (disposes callbacks, shuts down the native host) and surfaces the failure as InvalidOperationException so the async start task fails visibly.","triggerScenarios":"Calling StartAsync when the native runtime's connection-open entry point fails — e.g. the runtime library was loaded but is incompatible, corrupted, or its internal state is broken from a prior failed start/shutdown cycle.","commonSituations":"Mismatched native runtime binary vs managed wrapper version; a corrupted or partially installed runtime library; starting a second server after a prior native failure left the host in a bad state.","solutions":["Verify the FFI runtime library matches the version of the managed dotnet package (reinstall/restore to get a matched pair).","Check earlier log lines for a more specific native-side failure during connection open.","Dispose the FfiRuntimeHost fully and create a fresh instance instead of restarting a failed one.","Test loading the runtime library in isolation (PrepareNativeLibrary/bind path) to confirm exports resolve.","Capture native crash logs / run with debug logging enabled to see the runtime's own error before it returns 0."],"exampleFix":"// before\nvar host = Create(staleLibraryPath);\nawait host.StartAsync(token); // connection open fails\n// after\nvar host = Create(matchedRuntimeLibraryPath); // version-matched native lib\nawait host.StartAsync(token);","handlingStrategy":"try-catch","validationCode":"if (!File.Exists(runtimeLibraryPath)) throw new FileNotFoundException(runtimeLibraryPath); // plus version check of native lib vs package","typeGuard":"bool IsRuntimeUsable(FfiRuntimeHost? h) => h is not null && !h.IsDisposed;","tryCatchPattern":"try { await host.StartAsync(ct); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"connection_open failed\")) {\n    logger.LogError(ex, \"Runtime connection open failed; recreating host\");\n    host.Dispose(); host = FfiRuntimeHost.Create(resolvedLibraryPath);\n}","preventionTips":["Keep native runtime and managed package versions locked together","Enable debug logging around StartAsync to capture native-side causes","Avoid reusing a host instance after a failed start","Verify the native binary loads before starting servers"],"tags":["ffi","native-library","connection","startup-failure"],"backgroundTag":"connection-refused","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"}