iOfficeAI/OfficeCLI · error · CliException

plugin_idle_timeout

plugin_idle_timeout

Error message

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

What it means

CliException (code 'plugin_idle_timeout') thrown when the exporter's PluginProcess.Run reports IdleTimedOut — no stdout/stderr activity for `idle` seconds during an export. Idle budget comes from the manifest's idle_timeout_seconds.verbs.export; long-running exporters are expected to emit {"heartbeat":true} on stderr to reset the timer.

Source

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

            };

        bool residentClosed = false;
        if (ResidentClient.TryConnect(sourceFullPath, out _))
        {
            if (ResidentClient.SendCloseWithResponse(sourceFullPath, out _))
                residentClosed = true;
        }

        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",

View on GitHub (pinned to 1ced45e900)

Solutions

Raise idle_timeout_seconds.verbs.export in the manifest, or pass --timeout 0.
Add periodic {"heartbeat":true} writes to stderr in the exporter.
Investigate plugin stalls on the specific source file.

Example fix

// plugin: emit heartbeats during long work
while (working) {
    Console.Error.WriteLine("{\"heartbeat\":true}");
    DoChunk();
}

Defensive patterns

Strategy: retry

Validate before calling

var idle = plugin.Manifest.ResolveIdleTimeout("export");
if (idle > 0 && estimatedSeconds > idle)
    Console.Error.WriteLine($"Export may exceed idle budget {idle}s; consider --timeout 0.");

Try / catch

try { ExporterInvoker.Run(source, targetExt, outPath); }
catch (CliException ex) when (ex.Code == "plugin_idle_timeout")
{ /* retry with raised idle_timeout_seconds.verbs.export or --timeout 0 */ }

Prevention

Have exporters emit {"heartbeat":true} on stderr during long work.
Size idle_timeout_seconds.verbs.export to the largest expected file.
Use --timeout 0 for known-long unattended exports.

When it happens

Trigger: Exporter plugin stalls mid-export without emitting heartbeats; deadlock; slow network-attached output target.

Common situations: Large workbook/presentation export with no progress signalling; plugin blocked on a remote render service; default idle budget too tight for big files.

Related errors

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