[BUG] TypeError: agents is not iterable in RUV-Swarm loadSwarms method

[arturdr-ads]

GitHub Issue Content

---

Title: [BUG] TypeError: agents is not iterable in RUV-Swarm loadSwarms method

Bug Description

The RUV-Swarm MCP server crashes with a TypeError: agents is not iterable error when attempting to load swarm agents during swarm initialization. This occurs because of a missing await keyword when calling the async getSwarmAgents() method, causing the code to attempt iteration over a Promise object instead of an array.

Environment Details

• Package: ruv-swarm
• File Affected: src/mcp-tools-enhanced.js
• Error Location: Lines 447-450
• Node.js Version: Any version supporting async/await
• Operating System: Cross-platform (Node.js)

Exact Error Message

TypeError: agents is not iterable
    at EnhancedMcpTools.loadSwarms (file:///path/to/node_modules/ruv-swarm/src/mcp-tools-enhanced.js:447:31)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

Steps to Reproduce

1. Install and configure RUV-Swarm MCP server
2. Start the MCP server with swarm persistence enabled
3. Attempt to initialize a swarm that has agents stored in the database
4. The server will crash immediately when trying to load agents

Code Path:

// In loadSwarms method, around line 447:
const agents = this.persistence.getSwarmAgents(swarmData.id);  // Missing 'await'
console.log(`  └─ Loading ${agents.length} agents for swarm ${swarmData.id}`);  // agents is Promise

for (const agentData of agents) {  // TypeError: agents is not iterable
  // ... agent loading logic
}

Expected Behavior

• The getSwarmAgents() method should be properly awaited to return an array of agents
• The code should iterate over the actual agent array and spawn each agent successfully
• Swarm initialization should complete without errors
• Agents should be loaded and available for swarm operations

Actual Behavior

• getSwarmAgents() returns a Promise object (not awaited)
• The code attempts to access .length on a Promise (returns undefined)
• The for...of loop tries to iterate over the Promise object
• JavaScript throws TypeError: agents is not iterable
• Swarm initialization fails completely
• No agents are loaded, rendering the swarm non-functional

Root Cause Analysis

The issue stems from a fundamental async/await mistake:

1. Missing Await: The call to this.persistence.getSwarmAgents(swarmData.id) is not awaited
2. Promise vs Array: Without await, agents contains a Promise object, not the actual array
3. Iteration Failure: Promises are not iterable in JavaScript, causing the TypeError
4. No Validation: No type checking to ensure the value is an array before iteration

Additional Impact

• Complete Failure: Swarm initialization stops entirely
• Data Loss: Existing agents in the database cannot be loaded
• User Experience: MCP server becomes unusable for swarm operations
• Debugging Difficulty: Error message doesn't clearly indicate the missing await issue

Temporary Workaround

Currently, there is no viable workaround without modifying the source code. The bug completely prevents swarm initialization when agents are stored in the persistence layer.

Severity

CRITICAL - This bug prevents core functionality of the RUV-Swarm system and makes it impossible to use persisted swarms with agents.

Additional Context

This bug affects all users of RUV-Swarm who:

• Use swarm persistence (database storage)
• Have agents defined in their swarms
• Attempt to initialize swarms from saved state

The same async/await pattern issue also exists in the getActiveAgentIds() method around line 380, which could potentially cause similar issues in different code paths.

Files Created

• Bug fix implementation - Complete fix with defensive programming
• Git patch file - Ready-to-apply patch
• Detailed analysis - Technical explanation

Suggested Fix Priority

IMMEDIATE - This bug should be addressed in the next patch release as it prevents core functionality.

---

Labels: bug, critical, regression, swarm-loading, async-await