Troubleshooting

This guide helps recover from common issues when working with MCP Moira workflows.

When a conversation is archived or compacted, the agent loses:

• Current execution ID (processId)
• Workflow step context
• Progress information

The workflow state persists on the MCP server - only the agent’s memory is lost.

1. Find active executions:

session({ action: "executions" })

Returns list of executions with status, workflow ID, and notes:

[
  {
    "executionId": "abc-123",
    "workflowId": "development-flow",
    "status": "waiting",
    "note": "Feature: auth system",
    "currentNodeId": "implement-step"
  }
]

2. Get current step without advancing:

session({ action: "current_step", executionId: "abc-123" })

Returns the current directive and context:

{
  "directive": "Implement the feature...",
  "completionCondition": "Feature working and tested",
  "inputSchema": { ... }
}

3. Continue workflow:

step({ processId: "abc-123", input: { ... } })

To help future recovery, save the process ID in your workspace:

# Create process-id.txt in feature directory
echo "abc-123" > ./feature-name/process-id.txt

Include in session archives:

• Feature name
• Process ID
• Current step description

Lists all active workflow executions for current user.

Call: session({ action: "executions" })

Filters:

• status: Array of statuses - ["waiting", "running", "completed", "failed"]
• workflowId: Filter by specific workflow
• search: Search in execution notes

Example with filters:

session({
  action: "executions",
  status: ["waiting", "running"],
  search: "auth"
})

Retrieves current step directive without advancing the workflow.

Call: session({ action: "current_step", executionId: "..." })

Parameters:

• executionId (required): Execution ID to check

Returns:

• directive: What to do
• completionCondition: Success criteria
• inputSchema: Response structure

Gets full execution state including context variables.

Call: session({ action: "execution_context", executionId: "..." })

Parameters:

• executionId (required): Execution ID to inspect

Returns:

• executionId: Execution UUID
• workflowId: Workflow being executed
• status: Execution status (running, waiting, completed, failed)
• currentNodeId: Current node ID
• waitingForInputNodeId: Node waiting for input (if any)
• note: Execution note
• context.variables: Context variables
• context.nodeStates: Node execution states
• createdAt, updatedAt, completedAt: Timestamps
• error: Error message (if failed)

Cause: Invalid or expired processId

Solution:

1. Use session({ action: "executions" }) to find active executions
2. Use the correct executionId from the list
3. Process IDs are UUIDs like abc123-def456-...

Cause: Trying to advance a completed or failed execution

Solution:

1. Check execution status with session({ action: "execution_context", executionId: "..." })
2. Status must be waiting to accept input
3. If completed or failed, start a new execution

Cause: Input doesn’t match inputSchema

Solution:

1. Check inputSchema from current step
2. Verify field names match exactly (case sensitive)
3. Verify data types match (string vs number)
4. Include all required fields

Cause: Session was archived/compacted

Solution:

1. Check for process-id.txt in workspace
2. Use session({ action: "current_step" }) to get context
3. Remind agent: “Continue workflow {processId}“

User: Continue working on the auth feature

Agent:
1. session({ action: "executions", search: "auth" })
   → Found: executionId: "abc-123", status: "waiting"

2. session({ action: "current_step", executionId: "abc-123" })
   → directive: "Implement login endpoint"

3. [Does the work]

4. step({ processId: "abc-123", input: { result: "done" } })

User: What workflows am I running?

Agent:
1. session({ action: "executions" })
   → Lists all active executions with notes

2. session({ action: "execution_context", executionId: "abc-123" })
   → Shows full context including variables

Agent:
1. session({ action: "execution_context", executionId: "abc-123" })
   → status: "waiting", currentNodeId: "validation-step"

2. session({ action: "current_step", executionId: "abc-123" })
   → Shows what the workflow is waiting for

• MCP Agent Guide - Tool usage basics
• MCP Tools Reference - Full tool documentation