iOfficeAI/OfficeCLI · error · CliException

unsupported_command

unsupported_command

Error message

Format-handler plugin '{_plugin.Manifest.Name}' does not implement command '{command}'.

What it means

CliException (code 'unsupported_command') thrown by Send's capability gate: the plugin's declared Commands list (non-empty) does not contain the requested command. This short-circuits before any wire round-trip, avoiding a wasted request and ambiguous late errors.

Source

Thrown at src/officecli/Core/Plugins/FormatHandlerSession.cs:164

    /// <summary>
    /// Send a request envelope and synchronously wait for the matching reply.
    /// Throws <see cref="CliException"/> on protocol error, IO failure, or
    /// plugin-reported error responses.
    /// </summary>
    public JsonNode? Send(string msgType, string? command, JsonObject? args = null, JsonObject? props = null)
    {
        if (_disposed) throw new ObjectDisposedException(nameof(FormatHandlerSession));
        if (_broken)
            throw new CliException(
                $"Format-handler session for '{_plugin.Manifest.Name}' is no longer usable (stream was closed earlier).")
            { Code = "plugin_stream_closed" };

        // Capability gate: short-circuit verbs the plugin already declared it
        // does not support, avoiding a wasted round-trip and ambiguous errors.
        if (command is not null && _sessionCaps?.Capabilities?.Commands is { Count: > 0 } cmds
            && !cmds.Contains(command))
        {
            throw new CliException(
                $"Format-handler plugin '{_plugin.Manifest.Name}' does not implement command '{command}'.")
            { Code = "unsupported_command" };
        }

        var verbForTimeout = command ?? msgType;
        var idle = _plugin.Manifest.ResolveIdleTimeout(verbForTimeout);
        return SendRaw(msgType, command, args, props, idle);
    }

    private JsonNode? SendRaw(string msgType, string? command, JsonObject? args, JsonObject? props, int idleTimeoutSec)
    {
        if (_stdinWriter is null || _stdoutReader is null)
            throw new InvalidOperationException("Session not started.");

        var request = new JsonObject
        {
            ["protocol"] = 1,
            ["msg_type"] = msgType,

View on GitHub (pinned to 1ced45e900)

Solutions

1. Upgrade the plugin to a version that implements the command.
2. Switch to a plugin whose declared commands include the one you need (`officecli plugins list`).
3. Update the plugin manifest's commands list if the command is actually implemented but undeclared.

var cmds = session.Capabilities?.Capabilities?.Commands;
if (cmds is { Count: > 0 } && !cmds.Contains(command))
    throw new InvalidOperationException($"Plugin does not implement '{command}'.");

static bool PluginSupports(FormatHandlerSession s, string command) =>
    s.Capabilities?.Capabilities?.Commands is not { Count: > 0 } cmds || cmds.Contains(command);

try { session.Send("command", command, args); }
catch (CliException ex) when (ex.Code == "unsupported_command")
{ /* pick a plugin whose declared commands include 'command' */ }

When it happens

Trigger: Calling a FormatHandlerProxy method whose underlying Send passes a command not in _sessionCaps.Capabilities.Commands. Only fires when the plugin declared a non-empty Commands list (silent absence of a declaration means no gate).

Common situations: Host feature targets a command the plugin version omits; plugin manifest's commands list out of date; using a minimal plugin that declares only a subset (e.g. view-only) for a richer operation.

Related errors

• protocol_mismatch
• plugin_spawn_failed
• plugin_stream_closed
• dump_reader_not_found
• corrupt_batch

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