iOfficeAI/OfficeCLI · error · TimeoutException

Pipe communication timed out

Error message

Pipe communication timed out

What it means

Thrown by WatchNotifier.RunWithTimeout when a pipe action does not complete within the configured PipeTimeout. RunWithTimeout runs the action on a background Task and Task.Wait times out, throwing a TimeoutException so the calling thread never hangs if the watch server dies mid-conversation.

Source

Thrown at src/officecli/Core/Watch/WatchNotifier.cs:312

                result = true;
            }, PipeTimeout);
            return result;
        }
        catch
        {
            return false;
        }
    }

    /// <summary>
    /// Run an action on a background thread with a timeout.
    /// Prevents the calling thread from hanging if the pipe server dies mid-conversation.
    /// </summary>
    private static void RunWithTimeout(Action action, TimeSpan timeout)
    {
        var task = Task.Run(action);
        if (!task.Wait(timeout))
            throw new TimeoutException("Pipe communication timed out");
        task.GetAwaiter().GetResult(); // propagate exceptions
    }
}

/// <summary>
/// Message sent from command processes to the watch server via named pipe.
/// </summary>
internal class WatchMessage
{
    /// <summary>"replace", "add", "remove", or "full"</summary>
    public string Action { get; set; } = "full";

    /// <summary>Slide number (0 for full refresh)</summary>
    public int Slide { get; set; }

    /// <summary>Single slide HTML fragment (for replace/add)</summary>
    public string? Html { get; set; }

View on GitHub (pinned to 1ced45e900)

Solutions

1. Check that the watch process is alive and responsive (IsWatching / the watch URL).
2. Retry the operation once; if it persists, restart the watch.
3. If rendering huge docs, allow more time or split the work.

// Confirm a watch is running before issuing pipe commands
if (WatchNotifier.QueryMarksFull(filePath) is null) { /* no watch running; start one */ }

TimeSpan backoff = TimeSpan.FromMilliseconds(250);
for (int attempt = 0; attempt < 3; attempt++)
{
    try { return WatchNotifier.AddMark(filePath, request); }
    catch (TimeoutException) when (attempt < 2) { System.Threading.Thread.Sleep(backoff); backoff *= 2; }
}
return null; // give up after retries

When it happens

Trigger: The watch process is overloaded, deadlocked, or slow to respond to a mark/unmark/goto/get-marks/close pipe request; the named-pipe server accepted the connection but never replied within PipeTimeout.

Common situations: The watch process is busy rendering a large document; it crashed but the pipe endpoint lingers; system under heavy load; pipe buffer deadlock (writer/reader ordering).

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• plugin_idle_timeout
• {error}
• Another watch process is already running{url} for {_filePath
• body read timed out
• render timed out after 120s

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