Error Handling & Recovery
Relevant source files
The following files were used as context for generating this wiki page:
Error Handling and Recovery in the Nexus Orchestrator is designed to maintain the integrity of the "nervous system" for AI agents. As an autonomous infrastructure daemon, the system must handle failures in connectivity, workflow execution, and governance enforcement without manual intervention. The strategy focuses on local-first resilience, ensuring that agents can continue to function or safely fail-soft within their operating environments.
The system utilizes LangGraph for managing stateful workflows and Model Context Protocol (MCP) for communication, which inherently require robust recovery mechanisms to bridge the "infrastructure gap." Governance via OPA (Open Policy Agent) adds a layer of security-related error handling, where unauthorized actions are trapped and logged before they can impact the underlying infrastructure.
Workflow Orchestration Recovery
The orchestration layer uses LangGraph to manage complex workflows between AI agents and infrastructure. Recovery is focused on state persistence and the ability to resume or retry failed nodes in a graph.
State Persistence and Retries
Nexus leverages LangGraph’s ability to checkpoint state. If a background orchestration task fails, the persistent state layer allows the system to identify the last successful node and attempt a recovery.
The diagram above illustrates the typical flow when an orchestration task encounters an error, attempting retries before updating the persistent agent state.
Sources: README.md:12, nexus/orchestrator/workflow.py
Connectivity and Protocol Resilience
The Connectivity Layer utilizes the Model Context Protocol (MCP) to bridge agents with environments such as SSH or local containers. Errors in this layer usually involve network timeouts or credential failures.
MCP Communication Failures
When an MCP-based agent fails to communicate with the infrastructure daemon, the system implements a fallback mechanism to prevent the loss of agent context.
| Error Type | Detection Mechanism | Recovery Action |
|---|---|---|
| SSH Timeout | Connection Handshake | Automatic reconnect or environment reset |
| MCP Protocol Mismatch | Version Negotiation | Fallback to base protocol capabilities |
| Token Expiration | Zero Trust Auth | Re-authentication via Policy Engine |
Sources: README.md:10, nexus/connectivity/mcp_server.py
Governance and Security Faults
Nexus utilizes Open Policy Agent (OPA) and Zero Trust security for non-human identities. Error handling here is strictly defensive, treating unauthorized requests as fatal to the specific task but non-fatal to the daemon.
Policy Enforcement Errors
When a request violates a security policy, the Governance Layer intercepts the call and provides a structured error response that prevents the execution of unsafe infrastructure changes.
This sequence shows the interaction when an agent attempts an action that violates the Zero Trust governance model.
Sources: README.md:14, nexus/governance/policy_engine.py
Context and State Recovery
The Context Layer maintains AGENTS.md and other persistent files to track the "known world" of the orchestrator. Corruption or missing entries in these files trigger a reconciliation process.
Agent State Tracking
The AGENTS.md file serves as a registry. If an agent's trust level or description is missing, the orchestrator defaults to a "Zero Trust" posture until the identity is verified.
| Component | Responsibility | Failure Impact |
|---|---|---|
| AGENTS.md | Track Agent Identity | Loss of trust level leads to denied access |
| Context Files | Persistent State | Workflow resets to last known good checkpoint |
Sources: context/AGENTS.md:1-7, README.md:13
Conclusion
Error handling in Nexus Orchestrator is characterized by its local-first, autonomous nature. By combining LangGraph's state management with OPA's rigid security policies and MCP's structured communication, the system ensures that infrastructure management remains stable even when AI agents or underlying network layers experience faults. The primary objective remains bridging the "infrastructure gap" while maintaining a secure, zero-trust environment.