iOfficeAI/OfficeCLI · error · CliException

plugin_idle_timeout

plugin_idle_timeout

Error message

Dump-reader plugin '{plugin.Manifest.Name}' produced no output for {idle}s — likely hung.

What it means

CliException (code 'plugin_idle_timeout') thrown when PluginProcess.Run reports IdleTimedOut — the dump-reader produced no stdout for `idle` seconds. Idle timeout is resolved per-verb via the manifest's idle_timeout_seconds.verbs.dump.

Source

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

            {
                ExecutablePath = plugin.ExecutablePath,
                Arguments = new[] { "dump", sourceFullPath },
                IdleTimeoutSeconds = idle,
                OnStdoutLine = OnLine,
            });

            // Bubble up the per-line callback error first — its message is more
            // 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",

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Raise idle_timeout_seconds.verbs.dump in the plugin's manifest, or override with --timeout 0 for an unbounded run.
  2. Profile the plugin to find where it stalls; add periodic output/heartbeats.
  3. Confirm the source file is not corrupt or path-locked.

Example fix

// before (manifest)
"idle_timeout_seconds": { "default": 30 }

// after (manifest)
"idle_timeout_seconds": {
  "default": 30,
  "verbs": { "dump": 600 }
}
Defensive patterns

Strategy: retry

Validate before calling

var idle = plugin.Manifest.ResolveIdleTimeout("dump");
if (idle > 0 && estimatedWorkSeconds > idle)
    Console.Error.WriteLine($"Warning: work may exceed idle budget {idle}s; raise --timeout.");

Try / catch

try { DumpReaderInvoker.Run(source, ext); }
catch (CliException ex) when (ex.Code == "plugin_idle_timeout")
{ /* retry once with --timeout 0 or a higher idle_timeout_seconds.verbs.dump */ }

Prevention

When it happens

Trigger: Plugin started but stopped emitting JSONL lines; hung on input, deadlock, or waiting on a network resource. Distinguished from exit-code 6 (plugin_idle_timeout) which is plugin-reported.

Common situations: Plugin reads a huge/corrupt source synchronously with no progress output; plugin waits on a missing dependency; default idle budget too low for the dataset.

Related errors

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