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.

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)

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.