Debug a Failed Flow Run

You are helping the user debug a failed Power Automate flow run.

Tools

This skill uses the FlowAgent MCP tools. Clients surface them with a client-specific prefix — mcp__flowagent__<tool> (Claude Code) or flowagent-<tool> (Copilot CLI) — so they're referred to by bare name below (e.g. get_run_actions). Use CLI shell commands (local engine build only) for CLI-only operations or when no MCP tools are present.

Steps

1. Identify the flow and run
   • Parse $ARGUMENTS for flow ID and optional run ID.
   • If the user names an environment (or none is set), call resolve_environment first so the search runs in the right environment.
   • If no flow ID, call list_flows with name param to search. Ask user to pick if ambiguous.
   • If no run ID, call get_run_history and find the most recent failed run.
   • If get_run_history returns no runs, stop and say so plainly ("this flow has no recorded runs in its history"). Do not invent a failure, do not diagnose from the definition as if it had failed; offer to check the trigger configuration or to run/test the flow instead.
   • Present recent runs in a table: Run ID | Status | Start Time | Error
2. Fast triage with diagnose_run
   • Call diagnose_run for the run — it returns the failed/timed-out actions already classified with a remediation each. Use this as the starting point.
   • For deeper analysis, also fetch (in parallel): get_run_actions (full trace) and get_flow (definition context). For a failed loop, call get_run_action_repetitions on an action inside the loop to find the failing iteration.
   • Repetition results are { action, count, truncated, repetitions }; count is the returned count, not the total. If truncated is true, do not infer absence from the returned subset.
   • When recorded payloads are needed, use get_run_actions with includeSizes: true, then get_run_action_content with the action name and which: "inputs" or "outputs". The default download cap is 256000 bytes; an oversized result is reported rather than dumped. Retrieve only what the diagnosis needs and avoid reproducing sensitive payloads in the report.
3. Analyze failures
   • Identify actions with status != "Succeeded"
   • Trace the runAfter dependency chain to separate root cause from cascading failures:
     • Root cause: action whose dependencies all Succeeded but it failed
     • Cascading: actions skipped because a dependency failed
   • Report root cause actions with: name, type, error code, error message
4. Root cause classification
   • Connection errors (AuthorizationFailed, ConnectionNotFound, InvokerConnectionOverrideFailed): Suggest re-auth or fix connection source to Embedded
   • Expression errors (ExpressionEvaluationFailed, InvalidTemplate): Show the expression, explain what's wrong, suggest fix
   • API/External errors (401/403/404/429/500+): Explain the HTTP error, check connector status
   • Parameter errors (WorkflowOperationParametersRuntimeMissingValue): Missing/empty required parameter. Add null guard: @if(empty(...), 'default', ...)
   • Timeout (ActionTimedOut): Suggest retry policy or splitting the operation
   • Type mismatch (InvalidOpenApiConnectionOperationType): Wrong action type. Call get_operation_details to find correct type.
5. Suggest fix
   • Provide a specific fix with code/expression changes.
   • If the fix is a definition change, offer to apply it with edit_flow (surgical, one action/parameter) — fall back to update_flow only for large rewrites.
6. Re-test
   • Offer to call run_flow with wait: true to verify the fix works (or resubmit_run to retry the original run with its trigger inputs).
   • Report the result: Succeeded/Failed with action details.

Output Format

Diagnosis Summary

• Flow: [name] ([ID])
• Run: [run ID] | [start time] | Status: [status]

Failed Actions

Root Cause

Fix

[Step-by-step fix with code]