iOfficeAI/OfficeCLI · error · CliException

plugin_failed

plugin_failed

Error message

Plugin '{resolved.Manifest.Name}' dump failed (exit {runResult.ExitCode}) on fixture '{fixturePath}': {TruncateForLint(runResult.Stderr, 500)}

What it means

The plugin exited with a non-zero code after running 'dump <fixture>'. The message includes the exit code and up to 500 chars of the plugin's stderr (TruncateForLint) to surface the failure reason.

Solutions

  1. Read the included stderr (up to 500 chars) for the plugin's error.
  2. Run '<plugin> dump <fixture>' directly to reproduce and debug.
  3. Fix the plugin or supply a fixture it supports.

Example fix

# before: plugin exits 1 on the fixture
# reproduce directly:
./my-reader dump samples/tiny.foreign ; echo "exit=$?"
# fix the parser, then:
officecli plugins lint my-reader
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: run the plugin dump and require exit 0 before lint.
using var proc = Process.Start(plugin, $"dump {fixture}");
proc.WaitForExit();
if (proc.ExitCode != 0)
    throw new InvalidOperationException($"plugin dump failed (exit {proc.ExitCode}).");

Try / catch

// Lint runner: capture exit-code failures with their stderr.
try { LintPlugin(plugin, fixture); }
catch (CliException e) when (e.Code == "plugin_failed") {
    ReportPluginDefect($"{plugin}: {e.Message}");
}

Prevention

When it happens

Trigger: A dump-reader plugin crashes (uncaught exception), returns a non-zero exit on an unsupported fixture, or explicitly errors out.

Common situations: Fixture format the plugin does not handle; plugin bug/exception; missing native dependency the plugin needs to parse the fixture.

Related errors

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

Appendix: source

Thrown at src/officecli/CommandBuilder.Plugins.cs:315

                items.Add(item);
            }

            var idle = resolved.Manifest.ResolveIdleTimeout("dump");
            var runResult = PluginProcess.Run(new PluginProcess.RunOptions
            {
                ExecutablePath = resolved.ExecutablePath,
                Arguments = new[] { "dump", fixturePath },
                IdleTimeoutSeconds = idle,
                OnStdoutLine = OnLine,
            });
            if (PluginProcess.LineCallbackError is CliException ce) throw ce;
            if (PluginProcess.LineCallbackError is not null) throw PluginProcess.LineCallbackError;
            if (runResult.IdleTimedOut)
                throw new CliException(
                    $"Plugin '{resolved.Manifest.Name}' produced no output for {idle}s — likely hung.")
                { Code = "plugin_idle_timeout" };
            if (runResult.ExitCode != 0)
                throw new CliException(
                    $"Plugin '{resolved.Manifest.Name}' dump failed (exit {runResult.ExitCode}) on fixture '{fixturePath}': {TruncateForLint(runResult.Stderr, 500)}")
                { Code = "plugin_failed" };

            // Validate both add and set props against the target-format
            // schema. BatchItem.Type is used verbatim as the schema element
            // name for add; set commands look up the element via the path's
            // leaf type when available, falling back to lenient validation
            // when the schema doesn't recognize the inferred element.
            for (int i = 0; i < items.Count; i++)
            {
                var it = items[i];
                if (it is null) continue;
                var verb = (it.Command ?? "").ToLowerInvariant();
                if (verb != "add" && verb != "set") continue;
                if (it.Props == null || it.Props.Count == 0) continue;

                // For add: explicit Type. For set: best-effort infer from the
                // last segment of the path (e.g. "/p[1]/r[2]" → "r"). This

View on GitHub (pinned to 1ced45e900)