Troubleshooting & FAQ
Relevant source files
The following files were used as context for generating this wiki page:
This page provides technical guidance on identifying and resolving issues within the Nexus Orchestrator environment. As an autonomous infrastructure daemon, Nexus manages complex interactions between AI agents, Model Context Protocol (MCP) servers, and LangGraph-driven workflows.
Nexus operates as a "nervous system" for AI development, bridging the gap between high-level agent logic and low-level infrastructure such as SSH connectivity and persistent state management. Issues typically arise within the core pillars of connectivity, orchestration, context, and governance.
Sources: README.md:1-12
Core Pillar Framework
Understanding the system's structure is critical for troubleshooting. Nexus is built on four functional layers that must interact seamlessly.
| Pillar | Technology | Responsibility |
|---|---|---|
| Connectivity | MCP | Protocol for agent-to-infrastructure communication |
| Orchestration | LangGraph | Workflow management and state transitions |
| Context | AGENTS.md | Persistent state and agent tracking |
| Governance | OPA / Zero Trust | Security for non-human identities |
Sources: README.md:14-18
Architectural Data Flow
The following diagram illustrates how requests flow through the orchestrator. Troubleshooting should follow this path to identify where a process is failing.
This flow shows the transition from an agent's intent to infrastructure execution.
Sources: README.md:3-18, context/AGENTS.md:1-10
Troubleshooting Connectivity & MCP
The Connectivity Layer handles the bridge between agents and the infrastructure via the Model Context Protocol (MCP).
Connection Failures
If an agent cannot communicate with the orchestrator, verify the MCP server status. Common issues include:
- SSH Connectivity: The orchestrator manages SSH connectivity autonomously. Failures here prevent the agent from reaching target environments.
- Protocol Mismatch: Ensure the agent is using the correct MCP-based protocol version.
Sources: README.md:4-15
Troubleshooting Orchestration & Workflows
The Orchestration Layer utilizes LangGraph to manage workflows. Issues here usually manifest as stalled tasks or incorrect state transitions.
LangGraph State Issues
The orchestrator functions as an Autonomous Infrastructure Daemon. If a workflow fails to progress:
- Check the LangGraph workflow logic for circular dependencies.
- Verify if the "infrastructure gap" is being bridged—ensure the orchestrator has identified the correct target environment.
Sources: README.md:7-16
Troubleshooting Context & Agent Tracking
The Context Layer maintains the persistent state of known agents and their trust levels.
Agent Identification Failures
The system tracks interacting AI agents in the context/AGENTS.md file.
| Field | Description | Troubleshooting Step |
|---|---|---|
| Agent ID | Unique identifier for the agent | Verify the ID matches the incoming MCP metadata |
| Description | Role of the agent | Check if the agent's actions align with its description |
| Trust Level | Permission tier | Ensure the trust level is sufficient for the requested operation |
If an agent is not recognized or has an empty trust level, the Governance Layer may block its requests.
Sources: context/AGENTS.md:3-8, README.md:17-18
Troubleshooting Governance & Security
The Governance Layer implements OPA (Open Policy Agent) and Zero Trust security models specifically for non-human identities (AI agents).
Authorization Denied
When an agent request is blocked:
- Policy Check: Review the OPA policies governing agent actions.
- Zero Trust Identity: Ensure the agent's non-human identity is properly authenticated within the Zero Trust framework.
- Identity Verification: Cross-reference the agent's identity against the entries in
context/AGENTS.md.
Sources: README.md:18, context/AGENTS.md:3-8
Summary
Troubleshooting the Nexus Orchestrator requires a holistic view of its four pillars. By tracing an issue from the MCP Connectivity Layer through the LangGraph Orchestration and OPA Governance Layers, developers can isolate whether a failure is due to protocol communication, workflow logic, security policy, or state management in the Context Layer.