{"record":{"id":"c4ac0bf1e9ab2187","repo":"github/copilot-sdk","slug":"ffi-runtime-library-is-missing-the-export-expo","errorCode":null,"errorMessage":"FFI runtime library is missing the '{export}' export.","messagePattern":"FFI runtime library is missing the '(.+?)' export\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"critical","filePath":"dotnet/src/FfiRuntimeHost.cs","lineNumber":453,"sourceCode":"                throw new InvalidOperationException($\"Failed to load FFI runtime library '{libraryPath}'.\");\n            }\n\n            s_hostStart = Bind<HostStartDelegate>(handle, \"copilot_runtime_host_start\");\n            s_hostShutdown = Bind<HostShutdownDelegate>(handle, \"copilot_runtime_host_shutdown\");\n            s_connectionOpen = Bind<ConnectionOpenDelegate>(handle, \"copilot_runtime_connection_open\");\n            s_connectionWrite = Bind<ConnectionWriteDelegate>(handle, \"copilot_runtime_connection_write\");\n            s_connectionClose = Bind<ConnectionCloseDelegate>(handle, \"copilot_runtime_connection_close\");\n            s_loaded = true;\n            s_loadedPath = libraryPath;\n        }\n    }\n\n    private static T Bind<T>(IntPtr handle, string export) where T : Delegate\n    {\n        var symbol = NativeLoader.GetSymbol(handle, export);\n        if (symbol == IntPtr.Zero)\n        {\n            throw new InvalidOperationException($\"FFI runtime library is missing the '{export}' export.\");\n        }\n        return Marshal.GetDelegateForFunctionPointer<T>(symbol);\n    }\n\n    private static uint NativeHostStart(byte[] argvJson, byte[]? env) =>\n        s_hostStart!(argvJson, Len(argvJson.Length), env, env is null ? UIntPtr.Zero : Len(env.Length));\n\n    private uint NativeOpenConnection(uint serverId)\n    {\n        _outboundDelegate = OnOutbound;\n        return s_connectionOpen!(\n            serverId,\n            _outboundDelegate,\n            IntPtr.Zero,\n            null, UIntPtr.Zero,\n            null, UIntPtr.Zero,\n            null, UIntPtr.Zero);\n    }","sourceCodeStart":435,"sourceCodeEnd":471,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/dotnet/src/FfiRuntimeHost.cs#L435-L471","documentation":"Bind<T> resolves a named export via NativeLoader.GetSymbol and throws when the symbol pointer is zero — the loaded library exists but does not export a required copilot_runtime_* function. This fails fast instead of producing a null-function-pointer crash later.","triggerScenarios":"Loading a runtime library binary that is older/newer than the managed wrapper expects, so one of host_start, host_shutdown, connection_open, connection_write, etc. is absent.","commonSituations":"Version-skew between the managed dotnet package and a manually supplied native library; a stub or wrong binary placed at the library path; partially updated deployment replacing only one side.","solutions":["Reinstall the native runtime so its version matches the managed FfiRuntimeHost package.","Verify the binary really is the copilot FFI runtime (export list via dumpbin/nm) and not another DLL.","Align all deployment artifacts — never mix a new managed assembly with an old native lib.","Pin both managed and native components to the same release in CI and deployment."],"exampleFix":"// before\nCreate(legacyRuntimePath); // lacks copilot_runtime_connection_write\n// after\nCreate(versionMatchedRuntimePath); // exports all required symbols","handlingStrategy":"try-catch","validationCode":"// pre-flight: load and probe exports before Create\nusing var probe = NativeLibProbe.Open(libraryPath);\nforeach (var e in RequiredExports) if (!probe.HasExport(e)) throw new MissingExportException(e);","typeGuard":null,"tryCatchPattern":"try { host = FfiRuntimeHost.Create(libraryPath); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"missing the '\")) {\n    logger.LogError(ex, \"Runtime library incompatible: {Msg}\", ex.Message);\n    throw new ApplicationException(\"Native runtime version mismatch — reinstall matched runtime.\", ex);\n}","preventionTips":["Pin native library and managed package to the same release","Validate exports after deployment upgrades","Never mix old native binaries with new managed assemblies","Record the native library version at startup for diagnostics"],"tags":["ffi","native-library","missing-export","version-mismatch"],"backgroundTag":"incompatible-source-type","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}