Error Codes

Milo errors carry namespaced codes and optional repair context. Human CLIs format them for the terminal; MCPtools/callresponses expose the same context in errorDataso agents can retry with corrected arguments.

Base Type

All Milo errors derive fromMiloError:

from milo import ErrorCode, MiloError

raise MiloError(
    ErrorCode.FRM_VALIDATION,
    "Environment is required",
    argument="environment",
    constraint={"minLength": 1},
    suggestion="Provide a non-empty environment name.",
)

Constructor fields:

Error Classes

Error Codes

Gateway UI errors addresourceUri and reason. Lifecycle failures also add child, originalResourceUri, and the child JSON-RPC code when available. Common reasons areunknown_gateway_ui_resource, cli_unavailable, child_timeout, child_disconnected, child_parse_error, and child_transport_error.

Terminal Formatting

MiloError.format_compact()keeps terminal output short and actionable:

M-FRM-001 `environment`: Environment is required
  constraint: {'minLength': 1}
  hint: Provide a non-empty environment name.

Use format_error(exc)when boundary code needs to render arbitrary exceptions. It usesformat_compact() when available and falls back to TypeError: ... style text for plain exceptions.

MCP Tool Errors

MCPtools/callerrors are returned as tool results, not JSON-RPC protocol errors:

{
  "content": [{"type": "text", "text": "Error: ..."}],
  "isError": true,
  "errorData": {
    "tool": "deploy",
    "errorCode": "M-FRM-001",
    "type": "MiloError",
    "argument": "environment",
    "constraint": {"minLength": 1},
    "example": "x",
    "suggestion": "Provide a non-empty environment name.",
    "schema": {"type": "object", "properties": {"environment": {"type": "string"}}}
  }
}

For plain Python TypeErrorfrom a missing required argument, Milo parses the argument name and adds:

{
  "argument": "name",
  "reason": "missing_required_argument",
  "suggestion": "Provide 'name'."
}

Agents should use errorData.argument, errorData.constraint, errorData.reason, and errorData.schemato repair the next call. The content[0].textfield is for humans.

JSON-RPC Protocol Errors

The stdin/stdout MCP server maps exceptions that escape method dispatch to JSON-RPC error codes:

Most command handler failures should stay insidetools/call as isError tool results witherrorData.

Raising Repairable Errors

Prefer structured errors at validation boundaries:

from milo import ErrorCode, MiloError


def require_env(environment: str) -> None:
    if not environment:
        raise MiloError(
            ErrorCode.FRM_VALIDATION,
            "Environment is required",
            argument="environment",
            constraint={"minLength": 1},
            suggestion="Pass --environment staging or another non-empty value.",
        )

Do not raise broad plain exceptions when an agent could repair the call from a specific argument and constraint.