Introduction

This page covers strategies for diagnosing and fixing problems in CODI workflows. Whether you encounter CLI exit codes, agent failures, or unexpected UI behavior, follow these steps to pinpoint root causes and restore your development pipeline.

1. Common Errors & Exit Codes

• Exit Code 1: Findings above threshold (e.g., high-severity audit issues).

• Exit Code 2: Agent runtime error (e.g., syntax error in code, missing dependencies).

• Exit Code 3: Network or RPC failure during deploy.

• Solution Steps:

  1. Note command and flags used.

  2. Review summary message and error stack.

  3. Consult the CLI Command Reference for flag corrections.

2. Enabling Debug Logging

• CLI Flag: Add --verbose or -v to any codi command.

• UI Debug Mode: Append ?debug=true to the web app URL.

• Log Output: Look for ctx.logger.debug() entries showing MCP node IDs and A2A messages.

• Log Storage: Download logs from the Logs pane or retrieve via codi logs export.

3. Inspecting MCP Context Snapshots

• Snapshot Location: Stored under ~/.codi/mcp/snapshots/<timestamp>.json.

• CLI Command: codi mcp inspect --snapshot <timestamp> to view context tree.

• Checkpoints: Identify which agent node failed by locating the last successful snapshot.

• Rollbacks: Use codi deploy --rollback to revert to a known-good state.

4. Agent Failure Diagnostics

• Isolate Agent: Run a single agent (e.g., codi audit) to reproduce the error.

• Context Inputs: Export input artifacts via codi mcp extract --node <agent-node-id>.

• Local Debug: Launch agent with Node.js debugger or Rust backtrace enabled (RUST_BACKTRACE=1).

• Common Causes:

  • Missing templates or invalid paths for scaffold-agent.

  • Linter configuration errors for audit-agent.

  • Test framework mismatches for test-agent.

  • Wallet or network misconfiguration for deploy-agent.

5. CLI vs. Web UI Error Differences

• CLI: Direct stdout/stderr with exit codes; better for scripting and headless environments.

• Web UI: Errors surfaced in panels with stack traces; includes context tree and A2A message logs.

• Recommendation: Use CLI for reproducible debugging; use UI for interactive inspection of context and logs.

6. When to File an Issue

• Collect Artifacts: Include command, flags, log export, context snapshot, and environment details.

• Check Existing Issues: Search GitHub issues for similar problems.

• New Issue Template: Provide steps to reproduce, expected vs. actual behavior, and attach relevant JSON logs.

Conclusion

Effective troubleshooting in CODI relies on understanding exit codes, leveraging debug logs, inspecting MCP snapshots, and isolating failing agents. When all else fails, gather logs and context and file a detailed issue to get community support.