iOfficeAI/OfficeCLI · error · CliException

plugin_failed

plugin_failed

Error message

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

What it means

CliException thrown when the exporter exits non-zero. Exit-code mapping mirrors the dump-reader: 2=corrupt_input, 3=unsupported_feature, 4=license_expired, 5=protocol_mismatch, 6=plugin_idle_timeout, else plugin_failed. Stderr is truncated to 500 chars.

Source

Thrown at src/officecli/Core/Plugins/ExporterInvoker.cs:65

        var idle = plugin.Manifest.ResolveIdleTimeout("export");
        var result = PluginProcess.Run(new PluginProcess.RunOptions
        {
            ExecutablePath = plugin.ExecutablePath,
            Arguments = new[] { "export", sourceFullPath, "--out", outPath },
            IdleTimeoutSeconds = idle,
        });

        if (result.IdleTimedOut)
            throw new CliException(
                $"Exporter plugin '{plugin.Manifest.Name}' produced no output for {idle}s — likely hung.")
            {
                Code = "plugin_idle_timeout",
                Suggestion = "Override with --timeout 0 or raise `idle_timeout_seconds.verbs.export` in the plugin's manifest. " +
                             "Long-running exporters should also emit `{\"heartbeat\":true}` on stderr periodically.",
            };

        if (result.ExitCode != 0)
            throw new CliException(
                $"Exporter 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",
                },
            };

        if (!File.Exists(outPath))
            throw new CliException(
                $"Exporter plugin '{plugin.Manifest.Name}' reported success but no output file was written at {outPath}.")
            { Code = "plugin_contract_violation" };

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Read the mapped code and stderr snippet in the message.
  2. For corrupt_input (2): ensure the source opens in its native app and is not locked by a resident.
  3. For license_expired (4): renew the exporter's license.
  4. For unsupported_feature (3)/protocol_mismatch (5): upgrade the exporter to match the host.
Defensive patterns

Strategy: try-catch

Try / catch

try { ExporterInvoker.Run(source, targetExt, outPath); }
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; release resident locks if corrupt_input */ }

Prevention

When it happens

Trigger: Exporter process returns non-zero after PluginProcess.Run completes (idle-timeout is checked first).

Common situations: Corrupt/locked source (2); exporter cannot handle a feature in the file (3); expired exporter license (4); host/exporter protocol skew (5).

Related errors

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