{"record":{"id":"0720232cc7fd4bfb","repo":"felixse/FluentTerminal","slug":"winpty-error-msg-errorhandle","errorCode":null,"errorMessage":"winpty_error_msg(errorHandle)","messagePattern":"winpty_error_msg\\(errorHandle\\)","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"critical","filePath":"FluentTerminal.SystemTray/Services/WinPty/WinPtySession.cs","lineNumber":42,"sourceCode":"        {\n            _enableBuffer = false; // request.Profile.UseBuffer;\n\n            Id = request.Id;\n            _terminalsManager = terminalsManager;\n\n            var configHandle = IntPtr.Zero;\n            var spawnConfigHandle = IntPtr.Zero;\n            var errorHandle = IntPtr.Zero;\n\n            try\n            {\n                configHandle = winpty_config_new(WINPTY_FLAG_COLOR_ESCAPES, out errorHandle);\n                winpty_config_set_initial_size(configHandle, request.Size.Columns, request.Size.Rows);\n\n                _handle = winpty_open(configHandle, out errorHandle);\n                if (errorHandle != IntPtr.Zero)\n                {\n                    throw new Exception(winpty_error_msg(errorHandle));\n                }\n\n                var cwd = GetWorkingDirectory(request.Profile);\n                var args = request.Profile.Arguments;\n\n                if (!string.IsNullOrWhiteSpace(request.Profile.Location))\n                {\n                    args = $\"\\\"{request.Profile.Location}\\\" {args}\";\n                }\n\n                spawnConfigHandle = winpty_spawn_config_new(WINPTY_SPAWN_FLAG_AUTO_SHUTDOWN, request.Profile.Location, args, cwd, terminalsManager.GetDefaultEnvironmentVariableString(request.Profile.EnvironmentVariables), out errorHandle);\n                if (errorHandle != IntPtr.Zero)\n                {\n                    throw new Exception(winpty_error_msg(errorHandle));\n                }\n\n                _stdin = CreatePipe(winpty_conin_name(_handle), PipeDirection.Out);\n                _stdout = CreatePipe(winpty_conout_name(_handle), PipeDirection.In);","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/felixse/FluentTerminal/blob/ba83ec485eea8d8ee65825711731300bee2e76ed/FluentTerminal.SystemTray/Services/WinPty/WinPtySession.cs#L24-L60","documentation":"Thrown by WinPtySession.Start when winpty_open (the call that creates the winpty agent process) returns a non-null errorHandle. The winpty_error_msg(errorHandle) call extracts the human-readable error string from that handle; the message you see is winpty's own diagnostic for why the pseudoconsole could not be opened.","triggerScenarios":"After winpty_config_new and set_initial_size, winpty_open fails: winpty.dll/winpty-agent.exe are missing or the wrong architecture, the agent could not be spawned, or a previous handle leaked. errorHandle != IntPtr.Zero selects this branch.","commonSituations":"Bundled winpty binaries are missing, mismatched architecture (x86 vs x64), or wrong bitness for the process; agent executable blocked by antivirus; insufficient privileges to spawn the agent.","solutions":["Verify winpty.dll and winpty-agent.exe are deployed alongside the app and match the process architecture (x64).","Check the winpty_error_msg text for the exact OS-level reason and address it (missing DLL, access denied).","Whitelist the agent in antivirus/EDR if it is being blocked.","Fall back to the ConPty backend on Windows 10 1809+ where winpty is not required."],"exampleFix":"// before\n_handle = winpty_open(configHandle, out errorHandle);\nif (errorHandle != IntPtr.Zero)\n    throw new Exception(winpty_error_msg(errorHandle));\n\n// after - wrap with context\nthrow new Exception($\"winpty_open failed: {winpty_error_msg(errorHandle)}. Ensure winpty.dll and winpty-agent.exe match the process architecture.\");","handlingStrategy":"try-catch","validationCode":"// Verify winpty binaries are present and correct architecture before starting.\nif (!File.Exists(Path.Combine(appDir, \"winpty.dll\")) || !File.Exists(Path.Combine(appDir, \"winpty-agent.exe\")))\n    throw new DllNotFoundException(\"winpty.dll/winpty-agent.exe missing\");","typeGuard":null,"tryCatchPattern":"try { session.Start(request, manager); }\ncatch (Exception ex) { logger.Error(ex, \"winpty_open failed\"); fallbackToConPty(); }","preventionTips":["Ship winpty.dll and winpty-agent.exe matching the process architecture (x64).","Whitelist the agent in antivirus/EDR.","Prefer the ConPty backend on Windows 10 1809+ to avoid winpty entirely.","Log winpty_error_msg output for diagnosis."],"tags":["winpty","native","terminal-backend","pinvoke","shell"],"backgroundTag":null,"analyzedSha":"ba83ec485eea8d8ee65825711731300bee2e76ed","analyzedAt":"2026-08-13T21:23:15.467Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}