iOfficeAI/OfficeCLI · error · CliException

plugin_idle_timeout

plugin_idle_timeout

Error message

Plugin '{resolved.Manifest.Name}' produced no output for {idle}s — likely hung.

What it means

The plugin produced no stdout output for the configured idle-timeout window (manifest.ResolveIdleTimeout("dump")), so PluginProcess flagged it as idle-timed-out — i.e. the plugin likely hung reading the fixture or computing the first item.

Source

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

                        $"Plugin '{resolved.Manifest.Name}' emitted invalid JSON at line #{items.Count}: {ex.Message}")
                    { Code = "plugin_contract_violation" };
                }
                if (item is null) return;
                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;

View on GitHub (pinned to 1ced45e900)

Solutions

Run the plugin directly: '<plugin> dump <fixture>' and confirm it emits lines.
Ensure the plugin flushes each line immediately (not buffered until exit).
Increase the idle timeout in the manifest if parsing legitimately needs more lead time.
Check the plugin is not waiting on stdin or a lock.

Example fix

# before: plugin buffers all output and flushes at end (looks hung until done)
# after:  flush per line
Console.Out.WriteLine(line); Console.Out.Flush();

Defensive patterns

Strategy: validation

Validate before calling

// Plugin author: smoke-test that the plugin emits within the idle window.
using var proc = Process.Start(plugin, $"dump {fixture}");
if (!proc.StandardOutput.ReadLineAsync().Wait(TimeSpan.FromSeconds(idle)))
    throw new TimeoutException("plugin emitted nothing within idle window");

Try / catch

// Lint runner: treat idle-timeout as a plugin defect, not a transient retry.
try { LintPlugin(plugin, fixture); }
catch (CliException e) when (e.Code == "plugin_idle_timeout") {
    ReportPluginDefect($"{plugin} hung (no output for {idle}s).");
}

Prevention

Flush stdout per line; do not buffer until exit.
Raise ResolveIdleTimeout in the manifest if the plugin needs long lead parsing.
Smoke-test 'dump <fixture>' directly before linting.
Retry is pointless for a genuine hang — fix the plugin.

When it happens

Trigger: A dump-reader plugin, given a fixture, opens it but never writes a line (deadlock, infinite loop, blocking read on a missing resource) within the idle window.

Common situations: Plugin blocks on a network resource; waits on stdin instead of reading the fixture path arg; a parsing bug causes an infinite loop before the first emit; fixture is huge and parsing is pathologically slow.

Related errors

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