Debug a Power Automate flow

Work the loop in order. Skip a step only when you already hold its output.

1. Resolve the flow. list_flows, match on display_name, keep the flow_id. Not there? It may be in another environment: list_environments (extras.py) shows which one the tools are pointed at. If a run is still going and doing damage, cancel_run it first and set_flow_state(..., "Stopped") the flow - cancelling undoes nothing, it only stops what has not run yet.
2. Find the failure. list_runs(flow_id, status="Failed"). Newest first.
3. Diagnose one run. explain_run(flow_id, run_id) on the newest failed run.
   • failed_actions[].error is the real error text, already resolved from the SAS-signed blob. Do not go fetch it yourself.
   • failed_actions empty while status is Failed means the TRIGGER failed. get_flow and inspect the trigger's condition and inputs.
   • The cause is usually upstream: read the succeeded outputs for the value that fed the failing action.
4. Error clear but cause not ("it worked yesterday", intermittent, data-dependent): compare_runs(flow_id, failed_run_id). It auto-picks the most recent Succeeded run as baseline. Read diverged_at first, then output_changes - an action that succeeded in both runs with different output is usually the real cause. only_in_failed / only_in_baseline means a condition or branch evaluated differently.
5. Recurring or flaky: analyze_flow_health(flow_id). Trust the verdict:
   • broken (near-100% failure) - fix the definition, stop rerunning it
   • flaky, concentrated in one action - targeted fix on that action
   • flaky, spread across actions - suspect trigger data or a connection, not logic
6. Fix and verify. get_flow -> edit the returned definition -> update_flow_definition with the COMPLETE definition (there is no partial update). Verify on the data that broke it: resubmit_run(flow_id, run_id) on the failed run (extras.py) replays its original payload. run_flow starts a fresh run with no payload, so for any flow fed by real data a green result there proves nothing about this failure. Then list_runs and explain_run again.

Rules learned the hard way

• SAS URLs on old runs expire. If explain_run reports the error blob unavailable, re-run the flow and diagnose the fresh run instead of digging.
• run_flow does not forward a body: @triggerBody() is null when triggered through the management API. If the failure only reproduces with a real payload, call the flow's actual HTTP trigger URL.
• Deterministic vs data-dependent: the same action failing in both compared runs with empty output_changes means the definition is wrong. Different upstream outputs mean the data is.
• When the error points at the action's shape rather than its data (a missing or unknown parameter, an operation that no longer exists), check the connector reference with the Microsoft Learn MCP server before editing the definition. Fetch https://learn.microsoft.com/connectors/<connector>/ and confirm the operationId, its keys, and whether it is marked [DEPRECATED].