Skip to content

errors

nimblebrain_server_sdk.errors · install nimblebrain-server-sdk · version 0.7.2

from nimblebrain_server_sdk.errors import CapacityRefusal, ErrorCode, HostCapabilityMissing

The errors a server raises and the errors it returns.

HostCapabilityMissing signals a local condition (“this connection cannot carry a host-resources request”) rather than a wire response. Wire-level errors from the host come through as mcp.shared.exceptions.MCPError; the SDK does not wrap those, so server code matches on the JSON-RPC error code through the standard exception path. The other errors the SDK raises are ValueError and TypeError for a bad argument at registration or call time, MissingExtraError for a subpackage imported without its extra, and, from the extras, the errors each documents ([db]’s AuthError, Overloaded, PoolConfigError and UnsafeRoleError).

The rest is the service error contract: how a server reports a failure that crosses its boundary, so every server fails the same way and no upstream’s internals reach the host.

  • ServiceError is the typed failure. Its code is one of the closed set in ErrorCode, which fixes the HTTP status a host presents and whether a retry can help. message crosses to the host and stays generic; detail is for operators and goes to logs only.
  • ServiceError.from_upstream classifies a raw upstream HTTP status into that set.
  • to_tool_error turns a ServiceError into the FastMCP tool result to return, and rate_limited_tool_error does the same for a call refused for capacity.
  • add_error_contract (in the package root) makes a server return either one for a ServiceError or capacity refusal a tool raises, so a tool need not catch them.

Surfacing an error also records it: one service_error log line and one increment of service_errors_total{service, code, upstream_status}. Both come from nimblebrain_server_sdk.observability when the [observability] extra is installed. Without it the tool result is the same, the metric is not recorded, and the log line goes to the standard library logger nimblebrain_server_sdk.errors. This module imports neither the extra nor FastMCP until an error is surfaced.

def rate_limited_tool_error(refusal: CapacityRefusal) -> Any

The rate_limited tool error for a call refused for capacity, to return.

Classified, counted and logged like any ServiceError. The host sees the refusal’s own message and what to do next; the code is retryable, and the call ran nothing.

def to_tool_error(err: ServiceError) -> Any

A real fastmcp.ToolResult(is_error=True) to return from a tool.

Returns the FastMCP result object — NOT a dict. Returning a plain dict does NOT work: FastMCP scores a returned dict as is_error=False (a success with the flag buried in structured data), which reproduces the very in-band-error footgun this contract exists to prevent. The sanitized message is the text block; structured_content.error carries the envelope.

Imports fastmcp when called, so importing this module does not.

class CapacityRefusal(Protocol)

A call refused for capacity before it ran anything, carrying host-safe text.

nimblebrain_server_sdk.db.Overloaded is one; this module names the shape rather than the class, so it takes no database dependency.

class ErrorCode(StrEnum)

The closed set of cross-cutting error codes.

class HostCapabilityMissing(capability_key: str, *, protocol_version: str | None = None)

Raised by a host-resources call the connection cannot carry.

Either the host did not advertise the capability, or the connection negotiated the 2026-07-28 protocol, which has no channel for a request from a server to its client. The message says which. Catch it, or check host(ctx).available first, and return a tool error that tells the agent to pass the content inline instead:

try:
result = await host(ctx).read(seed_uri)
except HostCapabilityMissing:
return to_tool_error(
ServiceError(
ErrorCode.BAD_INPUT,
"This connection cannot read workspace files. Pass the file's contents "
"in `seed_data` instead.",
)
)

protocol_version is the negotiated version when the protocol era is the cause, else None.

class ServiceError(code: ErrorCode, message: str | None = None, *, upstream_status: int | None = None, retryable: bool | None = None, detail: str | None = None)

A classified, host-safe failure crossing a service boundary.

message crosses the trust boundary to the host — keep it generic; NEVER put a vendor name/URL, raw upstream body, secret, or tenant data in it. detail is operator-only (logs); it never reaches the host envelope.

Domain-specific failures subclass this and override metric_code to roll up to one of the cross-cutting codes for the metric label (so the service_errors_total{code=...} label stays the closed set).

def from_upstream(status: int, message: str | None = None, *, detail: str | None = None) -> ServiceError

Build from a raw upstream HTTP status (the common provider-error path).

The bare status number is stamped as host-safe upstream_status; the vendor’s prose belongs in detail (logs only), never in message. Omit message to use the classified code’s host-safe default.

metric_code: str

The closed-set code used as the service_errors_total label.

Cross-cutting errors are their own code; domain subclasses override this to roll up, keeping the metric’s label set bounded.

def to_envelope() -> dict[str, object]

The host-safe error payload (HTTP body / MCP structuredContent.error).