# How OfficeCLI Error Codes Enable Self-Healing Agent Workflows

> Discover how OfficeCLI error codes facilitate self-healing agent workflows. Enable automated failure detection, classification, and recovery without manual intervention.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-08-10

---

**OfficeCLI leverages standardized JSON-RPC 2.0 error codes to let automated agents detect, classify, and recover from failures without human intervention.**

The iOfficeAI/OfficeCLI project implements a machine-readable error protocol that transforms runtime failures into structured remediation opportunities. By adopting the JSON-RPC 2.0 error model across its core server components, OfficeCLI provides deterministic signals that self-healing agents can act upon programmatically.

## Understanding the JSON-RPC 2.0 Error Model in OfficeCLI

OfficeCLI structures every error response as a JSON envelope containing a numeric error code, a human-readable message, and optional metadata. This format originates in [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs), where the server constructs error payloads through the `ErrorJson()` helper method.

The four primary error codes map to distinct failure modes:

| Code | Meaning | Source Location |
|:---|:---|:---|
| **-32600** | Invalid Request — malformed JSON or illegal characters | [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) line 95: `ErrorJson(null, -32600, msg)` |
| **-32601** | Method Not Found — requested RPC method does not exist | [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) line 123: `ErrorJson(id, -32601, …)` |
| **-32602** | Invalid Params — missing or incorrectly typed parameters | [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) line 207: `ErrorJson(id, -32602, "Missing params")` |
| **-32603** | Internal Error — unexpected exception during request handling | [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) line 135: `ErrorJson(id, -32603, $"Internal error: {ex.Message}")` |

These codes propagate through the `ResidentServer` layer, which wraps errors into response envelopes via `MakeResponse(1, "", $"Error: …")` at lines 913-917 of [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs). The CLI simultaneously writes messages to `Console.Error` for human users while preserving the structured JSON for automated consumers.

## Mapping Error Codes to Agent Remediation Strategies

Self-healing agents interpret OfficeCLI error codes as decision triggers. Each code indicates a specific recovery path:

### -32600: Input Validation Failure

Agents receiving this code should reject the request immediately and verify input encoding. The malformed payload cannot be salvaged; upstream correction is required.

### -32601: Method Discovery Failure

Agents can fallback to default commands or query alternative tool registries. This error signals a capability mismatch rather than a runtime fault.

### -32602: Parameter Recovery

Missing or invalid parameters enable the richest remediation opportunities. Agents may:

- Auto-populate defaults from configuration schemas
- Prompt users interactively for required values
- Infer parameters from context or previous operations

### -32603: Transient Internal Failure

Unexpected exceptions warrant retry logic with exponential back-off or failover to redundant service instances. This code distinguishes recoverable infrastructure issues from permanent logic errors.

## Practical Implementation Examples

### Triggering a JSON-RPC Error from a Plugin

```csharp
// Inside a plugin command handler
if (string.IsNullOrEmpty(request.Args["path"]))
{
    // Missing required argument → return -32602
    return OfficeCli.CommandBuilder.MakeResponse(
        1, "", $"Error: {OfficeCli.Core.MsysPathHint.AugmentMessage("Missing 'path' argument")}");
}

```

The `CommandBuilder.MakeResponse()` method standardizes error formatting across all OfficeCLI commands, ensuring consistent envelope structure.

### Python Agent Auto-Healing Missing Parameters

```python
import json
import time
import requests

def call_officecli(payload):
    r = requests.post("http://localhost:1234/rpc", json=payload)
    resp = r.json()
    
    if resp.get("error"):
        code = resp["error"]["code"]
        if code == -32602:  # Missing params

            # Insert sensible default and retry

            payload["params"]["path"] = "./default.pptx"
            time.sleep(0.5)  # Simple back-off

            return call_officecli(payload)
    
    return resp

# Initial (faulty) request without required path parameter

result = call_officecli({"jsonrpc": "2.0", "method": "render", "params": {}})
print(json.dumps(result, indent=2))

```

### Go Agent Handling Internal Errors with Failover

```go
func handleError(err jsonrpcError) {
    switch err.Code {
    case -32603:
        // Try alternative rendering engine
        switchBackend("chromium")
        retry()
    default:
        log.Fatalf("Unrecoverable error: %s", err.Message)
    }
}

```

## Key Source Files for Error Handling

| File | Responsibility |
|:---|:---|
| [`src/officecli/McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs) | JSON-RPC server emitting error envelopes with standardized codes |
| [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) | Wraps errors for resident-mode operation, mirrors non-resident path |
| [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) | Configures `Console.Error` redirection for human-readable output |
| [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) | Generates final CLI responses including error formatting via `MakeResponse` |

## Cross-Language and Cross-Plugin Consistency

Because OfficeCLI error codes derive from the JSON-RPC 2.0 specification rather than ad-hoc conventions, the same agent logic applies uniformly across:

- All OfficeCLI subcommands and plugins
- Language SDKs that re-export the error envelope
- Third-party integrations consuming the RPC interface

This standardization eliminates special-case handling and reduces agent complexity.

## Summary

- **OfficeCLI error codes follow JSON-RPC 2.0**, providing predictable, machine-parseable failure signals
- **Four core codes (-32600 through -32603)** cover malformed requests, missing methods, invalid parameters, and internal exceptions
- **Self-healing agents map each code to specific remediation**: validation, fallback, auto-completion, or retry with failover
- **[`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) and [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)** implement the error generation and propagation pipeline
- **Standardized envelopes enable portable agent logic** across commands, plugins, and language bindings

## Frequently Asked Questions

### How does OfficeCLI format error responses for automated consumption?

OfficeCLI returns JSON-RPC 2.0 error objects containing `code`, `message`, and optional `data` fields. The [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) file constructs these envelopes via `ErrorJson()`, and [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) wraps them for resident-mode operations. Automated agents parse this structure without scraping human-readable console output.

### Can agents distinguish between permanent errors and retryable failures?

Yes. OfficeCLI uses `-32603` exclusively for unexpected internal exceptions, signaling that retry or failover may succeed. Codes `-32600`, `-32601`, and `-32602` indicate client-side or request-level issues that will not resolve through repetition and require request modification.

### Where does OfficeCLI write errors for human users versus machines?

Human-oriented messages route through `Console.Error` as configured in [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs). Machine-oriented JSON envelopes travel through the RPC response channel. The [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) layer maintains both pathways simultaneously, ensuring no information loss for either audience.