{"record":{"id":"a764bb2c777ae009","repo":"iOfficeAI/OfficeCLI","slug":"plugin-spawn-failed","errorCode":"plugin_spawn_failed","errorMessage":"Failed to start format-handler plugin '{_plugin.Manifest.Name}'.","messagePattern":"Failed to start format-handler plugin '(.+?)'\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"src/officecli/Core/Plugins/FormatHandlerSession.cs","lineNumber":87,"sourceCode":"            ArgumentList = { \"open\", _filePath },\n            UseShellExecute = false,\n            RedirectStandardInput = true,\n            RedirectStandardOutput = true,\n            RedirectStandardError = true,\n            CreateNoWindow = true,\n            // Force UTF-8 no-BOM on all three streams. Windows defaults to\n            // Console.InputEncoding/OutputEncoding which can be GBK/CP1252\n            // depending on locale — wire format must be locale-independent.\n            StandardInputEncoding = utf8NoBom,\n            StandardOutputEncoding = utf8NoBom,\n            StandardErrorEncoding = utf8NoBom,\n        };\n        var selfPath = Environment.ProcessPath;\n        if (!string.IsNullOrEmpty(selfPath))\n            psi.Environment[\"OFFICECLI_BIN\"] = selfPath;\n\n        _proc = Process.Start(psi)\n            ?? throw new CliException($\"Failed to start format-handler plugin '{_plugin.Manifest.Name}'.\")\n                { Code = \"plugin_spawn_failed\" };\n\n        // Wrap stdin with an explicit UTF-8 no-BOM writer on the base\n        // stream. Process.StandardInput's default StreamWriter buffers\n        // independently and (on some runtimes) ignores AutoFlush — going\n        // direct to BaseStream avoids the surprise.\n        _stdinWriter = new StreamWriter(_proc.StandardInput.BaseStream, utf8NoBom, bufferSize: 8192, leaveOpen: true)\n        {\n            AutoFlush = true,\n            NewLine = \"\\n\",\n        };\n        _stdoutReader = _proc.StandardOutput;\n        Volatile.Write(ref _lastActivityTicks, DateTime.UtcNow.Ticks);\n\n        // Background stderr pump: heartbeat lines (`{\"heartbeat\":true}`)\n        // reset the activity timer; everything else is diagnostic noise we\n        // drain to keep the OS pipe buffer from filling and blocking the\n        // plugin. We intentionally do not surface the diagnostic text here","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Core/Plugins/FormatHandlerSession.cs#L69-L105","documentation":"CliException (code 'plugin_spawn_failed') thrown when Process.Start returns null for a format-handler plugin. PSI is configured with UTF-8 no-BOM on all three streams and injects OFFICECLI_BIN from Environment.ProcessPath. Process.Start returning null is rare on modern runtimes (it usually throws on failure).","triggerScenarios":"Spawning the format-handler plugin's executable path returned null — most commonly the path does not exist, is not executable, or the runtime could not create the process handle.","commonSituations":"Plugin executable moved/uninstalled after registration; execute permission missing on Linux/macOS; path with spaces or non-ASCII mishandled in manifest; antivirus blocking process creation on Windows.","solutions":["Verify plugin.ExecutablePath exists and is executable (chmod +x on Unix).","Re-register or reinstall the plugin to refresh the executable path.","Check antivirus/EDR is not blocking the spawn; capture Process.Start's inner exception if any."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (!File.Exists(plugin.ExecutablePath))\n    throw new InvalidOperationException($\"Plugin executable missing: {plugin.ExecutablePath}\");\nif (!RuntimeInformation.IsOSPlatform(OSPlatform.Windows))\n    File.SetUnixPermissionOrThrow(plugin.ExecutablePath, UnixFileMode.UserExecute);","typeGuard":null,"tryCatchPattern":"try { session = new FormatHandlerSession(plugin); }\ncatch (CliException ex) when (ex.Code == \"plugin_spawn_failed\")\n{ /* verify executable path/permissions; reinstall plugin */ }","preventionTips":["Verify the executable path exists and is executable before starting a session.","Re-register plugins after relocating their binaries.","Check AV/EDR policy isn't blocking process creation."],"tags":["plugins","format-handler","process","spawn","cli-exception"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}