iOfficeAI/OfficeCLI · error · CliException

plugin_failed

plugin_failed

Error message

Dump-reader plugin '{plugin.Manifest.Name}' failed (exit {result.ExitCode}): {Truncate(result.Stderr, 500)}

What it means

CliException thrown when the dump-reader exits non-zero. Code is mapped from the exit code: 2=corrupt_input, 3=unsupported_feature, 4=license_expired, 5=protocol_mismatch, 6=plugin_idle_timeout, otherwise plugin_failed. Stderr is truncated to 500 chars via DisplayText.Truncate.

Source

Thrown at src/officecli/Core/Plugins/DumpReaderInvoker.cs:126

            // actionable than the generic non-zero exit that follows.
            if (PluginProcess.LineCallbackError is CliException ce)
                throw ce;
            if (PluginProcess.LineCallbackError is not null)
                throw new CliException(
                    $"Dump-reader plugin '{plugin.Manifest.Name}' replay aborted: {PluginProcess.LineCallbackError.Message}",
                    PluginProcess.LineCallbackError)
                { Code = "plugin_command_failed" };

            if (result.IdleTimedOut)
                throw new CliException(
                    $"Dump-reader plugin '{plugin.Manifest.Name}' produced no output for {idle}s — likely hung.")
                {
                    Code = "plugin_idle_timeout",
                    Suggestion = $"Override with --timeout 0 or set a longer `idle_timeout_seconds.verbs.dump` in the plugin's manifest.",
                };

            if (result.ExitCode != 0)
                throw new CliException(
                    $"Dump-reader plugin '{plugin.Manifest.Name}' failed (exit {result.ExitCode}): {Truncate(result.Stderr, 500)}")
                {
                    Code = result.ExitCode switch
                    {
                        2 => "corrupt_input",
                        3 => "unsupported_feature",
                        4 => "license_expired",
                        5 => "protocol_mismatch",
                        6 => "plugin_idle_timeout",
                        _ => "plugin_failed",
                    },
                };

            // v6.4: now that the plugin has exited and all JSONL is buffered,
            // open the handler on this thread and replay synchronously. See
            // the rationale comment at the bufferedLines declaration above
            // (OpenXml SDK package state not thread-safe under heavy
            // multi-part Update-mode mutation).

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Read the mapped code and truncated stderr in the message — they name the failure class.
  2. For corrupt_input (2): validate the source file opens in its native app.
  3. For license_expired (4): refresh the plugin's license/subscription.
  4. For unsupported_feature (3) / protocol_mismatch (5): upgrade the plugin to match the host.
Defensive patterns

Strategy: try-catch

Try / catch

try { DumpReaderInvoker.Run(source, ext); }
catch (CliException ex) when (ex.Code is "corrupt_input" or "unsupported_feature" or "license_expired" or "protocol_mismatch" or "plugin_failed")
{ /* branch on ex.Code for user-facing guidance */ }

Prevention

When it happens

Trigger: Plugin process returns any non-zero exit code after PluginProcess.Run completes. The idle-timeout and line-callback-error paths are checked first and short-circuit before this.

Common situations: Source file the plugin cannot parse (exit 2); plugin feature gap (exit 3); license/subscription expired (exit 4); host/plugin protocol version skew (exit 5).

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/bb3272e3ff0ddd4b. Report an issue: GitHub.