{"kind":"Skill","metadata":{"namespace":"community","name":"flowstudio-power-automate-debug","version":"0.1.0"},"spec":{"description":"\u003e-","files":{"SKILL.md":"---\nname: flowstudio-power-automate-debug\ndescription: \u003e-\n  Debug failing Power Automate cloud flows using the FlowStudio MCP server.\n  The Graph API only shows top-level status codes. This skill gives your agent\n  action-level inputs and outputs to find the actual root cause.\n  Load this skill when asked to: debug a flow, investigate a failed run, why is\n  this flow failing, inspect action outputs, find the root cause of a flow error,\n  fix a broken Power Automate flow, diagnose a timeout, trace a DynamicOperationRequestFailure,\n  check connector auth errors, read error details from a run, or troubleshoot\n  expression failures. Requires a FlowStudio MCP subscription — see https://mcp.flowstudio.app\n---\n\n# Power Automate Debugging with FlowStudio MCP\n\nA step-by-step diagnostic process for investigating failing Power Automate\ncloud flows through the FlowStudio MCP server.\n\n\u003e **Real debugging examples**: [Expression error in child flow](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/fix-expression-error.md) |\n\u003e [Data entry, not a flow bug](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/data-not-flow.md) |\n\u003e [Null value crashes child flow](https://github.com/ninihen1/power-automate-mcp-skills/blob/main/examples/null-child-flow.md)\n\n**Prerequisite**: A FlowStudio MCP server must be reachable with a valid JWT.\nSee the `flowstudio-power-automate-mcp` skill for connection setup.\nSubscribe at https://mcp.flowstudio.app\n\n---\n\n## Source of Truth\n\n\u003e **Always call `list_skills` / `tool_search` first** to confirm available tool\n\u003e names and parameter schemas. Tool names and parameters may change between\n\u003e server versions.\n\u003e This skill covers response shapes, behavioral notes, and diagnostic patterns —\n\u003e things tool schemas cannot tell you. If this document disagrees with\n\u003e `tool_search` or a real API response, the API wins.\n\n---\n\n## Python Helper\n\n```python\nimport json, urllib.request\n\nMCP_URL   = \"https://mcp.flowstudio.app/mcp\"\nMCP_TOKEN = \"\u003cYOUR_JWT_TOKEN\u003e\"\n\ndef mcp(tool, **kwargs):\n    payload = json.dumps({\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/call\",\n                          \"params\": {\"name\": tool, \"arguments\": kwargs}}).encode()\n    req = urllib.request.Request(MCP_URL, data=payload,\n        headers={\"x-api-key\": MCP_TOKEN, \"Content-Type\": \"application/json\",\n                 \"User-Agent\": \"FlowStudio-MCP/1.0\"})\n    try:\n        resp = urllib.request.urlopen(req, timeout=120)\n    except urllib.error.HTTPError as e:\n        body = e.read().decode(\"utf-8\", errors=\"replace\")\n        raise RuntimeError(f\"MCP HTTP {e.code}: {body[:200]}\") from e\n    raw = json.loads(resp.read())\n    if \"error\" in raw:\n        raise RuntimeError(f\"MCP error: {json.dumps(raw['error'])}\")\n    return json.loads(raw[\"result\"][\"content\"][0][\"text\"])\n\nENV = \"\u003cenvironment-id\u003e\"   # e.g. Default-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\n```\n\n---\n\n## Step 1 — Locate the Flow\n\n```python\nresult = mcp(\"list_live_flows\", environmentName=ENV)\n# Returns a wrapper object: {mode, flows, totalCount, error}\ntarget = next(f for f in result[\"flows\"] if \"My Flow Name\" in f[\"displayName\"])\nFLOW_ID = target[\"id\"]   # plain UUID — use directly as flowName\nprint(FLOW_ID)\n```\n\n---\n\n## Step 2 — Find the Failing Run\n\n```python\nruns = mcp(\"get_live_flow_runs\", environmentName=ENV, flowName=FLOW_ID, top=5)\n# Returns direct array (newest first):\n# [{\"name\": \"08584296068667933411438594643CU15\",\n#   \"status\": \"Failed\",\n#   \"startTime\": \"2026-02-25T06:13:38.6910688Z\",\n#   \"endTime\": \"2026-02-25T06:15:24.1995008Z\",\n#   \"triggerName\": \"manual\",\n#   \"error\": {\"code\": \"ActionFailed\", \"message\": \"An action failed...\"}},\n#  {\"name\": \"...\", \"status\": \"Succeeded\", \"error\": null, ...}]\n\nfor r in runs:\n    print(r[\"name\"], r[\"status\"], r[\"startTime\"])\n\nRUN_ID = next(r[\"name\"] for r in runs if r[\"status\"] == \"Failed\")\n```\n\n---\n\n## Step 3 — Get the Top-Level Error\n\n\u003e **CRITICAL**: `get_live_flow_run_error` tells you **which** action failed.\n\u003e `get_live_flow_run_action_outputs` tells you **why**. You must call BOTH.\n\u003e Never stop at the error alone — error codes like `ActionFailed`,\n\u003e `NotSpecified`, and `InternalServerError` are generic wrappers. The actual\n\u003e root cause (wrong field, null value, HTTP 500 body, stack trace) is only\n\u003e visible in the action's inputs and outputs.\n\n```python\nerr = mcp(\"get_live_flow_run_error\",\n    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID)\n# Returns:\n# {\n#   \"runName\": \"08584296068667933411438594643CU15\",\n#   \"failedActions\": [\n#     {\"actionName\": \"Apply_to_each_prepare_workers\", \"status\": \"Failed\",\n#      \"error\": {\"code\": \"ActionFailed\", \"message\": \"An action failed...\"},\n#      \"startTime\": \"...\", \"endTime\": \"...\"},\n#     {\"actionName\": \"HTTP_find_AD_User_by_Name\", \"status\": \"Failed\",\n#      \"code\": \"NotSpecified\", \"startTime\": \"...\", \"endTime\": \"...\"}\n#   ],\n#   \"allActions\": [\n#     {\"actionName\": \"Apply_to_each\", \"status\": \"Skipped\"},\n#     {\"actionName\": \"Compose_WeekEnd\", \"status\": \"Succeeded\"},\n#     ...\n#   ]\n# }\n\n# failedActions is ordered outer-to-inner. The ROOT cause is the LAST entry:\nroot = err[\"failedActions\"][-1]\nprint(f\"Root action: {root['actionName']} → code: {root.get('code')}\")\n\n# allActions shows every action's status — useful for spotting what was Skipped\n# See common-errors.md to decode the error code.\n```\n\n---\n\n## Step 4 — Inspect the Failing Action's Inputs and Outputs\n\n\u003e **This is the most important step.** `get_live_flow_run_error` only gives\n\u003e you a generic error code. The actual error detail — HTTP status codes,\n\u003e response bodies, stack traces, null values — lives in the action's runtime\n\u003e inputs and outputs. **Always inspect the failing action immediately after\n\u003e identifying it.**\n\n```python\n# Get the root failing action's full inputs and outputs\nroot_action = err[\"failedActions\"][-1][\"actionName\"]\ndetail = mcp(\"get_live_flow_run_action_outputs\",\n    environmentName=ENV,\n    flowName=FLOW_ID,\n    runName=RUN_ID,\n    actionName=root_action)\n\nif len(detail) \u003e 1:\n    print(f\"{root_action} returned {len(detail)} repetitions; inspect iteration indexes\")\nout = detail[0] if detail else {}\nprint(f\"Action: {out.get('actionName')}\")\nprint(f\"Status: {out.get('status')}\")\n\n# For HTTP actions, the real error is in outputs.body\nif isinstance(out.get(\"outputs\"), dict):\n    status_code = out[\"outputs\"].get(\"statusCode\")\n    body = out[\"outputs\"].get(\"body\", {})\n    print(f\"HTTP {status_code}\")\n    print(json.dumps(body, indent=2)[:500])\n\n    # Error bodies are often nested JSON strings — parse them\n    if isinstance(body, dict) and \"error\" in body:\n        err_detail = body[\"error\"]\n        if isinstance(err_detail, str):\n            err_detail = json.loads(err_detail)\n        print(f\"Error: {err_detail.get('message', err_detail)}\")\n\n# For expression errors, the error is in the error field\nif out.get(\"error\"):\n    print(f\"Error: {out['error']}\")\n\n# Also check inputs — they show what expression/URL/body was used\nif out.get(\"inputs\"):\n    print(f\"Inputs: {json.dumps(out['inputs'], indent=2)[:500]}\")\n```\n\n### What the action outputs reveal (that error codes don't)\n\n| Error code from `get_live_flow_run_error` | What `get_live_flow_run_action_outputs` reveals |\n|---|---|\n| `ActionFailed` | Which nested action actually failed and its HTTP response |\n| `NotSpecified` | The HTTP status code + response body with the real error |\n| `InternalServerError` | The server's error message, stack trace, or API error JSON |\n| `InvalidTemplate` | The exact expression that failed and the null/wrong-type value |\n| `BadRequest` | The request body that was sent and why the server rejected it |\n\n### Foreach iterations\n\nWhen `actionName` refers to an action inside a foreach, the output tool can\nreturn every repetition of that action. Each item may include\n`repetitionIndexes` with the loop name and zero-based `itemIndex`. Use\n`iterationIndex` to inspect one iteration after you find the suspicious item:\n\n```python\nall_reps = mcp(\"get_live_flow_run_action_outputs\",\n    environmentName=ENV,\n    flowName=FLOW_ID,\n    runName=RUN_ID,\n    actionName=root_action)\n\nfor rep in all_reps[:10]:\n    print(rep.get(\"repetitionIndexes\"), rep.get(\"status\"), rep.get(\"error\"))\n\none_rep = mcp(\"get_live_flow_run_action_outputs\",\n    environmentName=ENV,\n    flowName=FLOW_ID,\n    runName=RUN_ID,\n    actionName=root_action,\n    iterationIndex=3)\n```\n\n### Evidence Compose Bookends\n\nFor uncertain connector work, add a `Compose_*_Request` before the risky action\nand a `Compose_*_Result` after it, with the result action allowed on both\n`Succeeded` and `Failed`. This gives future debugging a clean payload snapshot\nwithout requiring another deploy. Do not include secrets or long binary payloads\nin these bookends.\n\n### Example: HTTP action returning 500\n\n```\nError code: \"InternalServerError\" ← this tells you nothing\n\nAction outputs reveal:\n  HTTP 500\n  body: {\"error\": \"Cannot read properties of undefined (reading 'toLowerCase')\n    at getClientParamsFromConnectionString (storage.js:20)\"}\n  ← THIS tells you the Azure Function crashed because a connection string is undefined\n```\n\n### Example: Expression error on null\n\n```\nError code: \"BadRequest\" ← generic\n\nAction outputs reveal:\n  inputs: \"body('HTTP_GetTokenFromStore')?['token']?['access_token']\"\n  outputs: \"\"   ← empty string, the path resolved to null\n  ← THIS tells you the response shape changed — token is at body.access_token, not body.token.access_token\n```\n\n---\n\n## Step 5 — Read the Flow Definition\n\n```python\ndefn = mcp(\"get_live_flow\", environmentName=ENV, flowName=FLOW_ID)\nactions = defn[\"properties\"][\"definition\"][\"actions\"]\nprint(list(actions.keys()))\n```\n\nFind the failing action in the definition. Inspect its `inputs` expression\nto understand what data it expects.\n\n---\n\n## Step 6 — Walk Back from the Failure\n\nWhen the failing action's inputs reference upstream actions, inspect those\ntoo. Walk backward through the chain until you find the source of the\nbad data:\n\n```python\n# Inspect multiple actions leading up to the failure\nfor action_name in [root_action, \"Compose_WeekEnd\", \"HTTP_Get_Data\"]:\n    result = mcp(\"get_live_flow_run_action_outputs\",\n        environmentName=ENV,\n        flowName=FLOW_ID,\n        runName=RUN_ID,\n        actionName=action_name)\n    out = result[0] if result else {}\n    print(f\"\\n--- {action_name} ({out.get('status')}) ---\")\n    print(f\"Inputs:  {json.dumps(out.get('inputs', ''), indent=2)[:300]}\")\n    print(f\"Outputs: {json.dumps(out.get('outputs', ''), indent=2)[:300]}\")\n```\n\n\u003e ⚠️ Output payloads from array-processing actions can be very large.\n\u003e Always slice (e.g. `[:500]`) before printing.\n\n\u003e **Tip**: Omit `actionName` to list top-level actions when you're not sure\n\u003e which action produced the bad data. Once you pick an action inside a foreach,\n\u003e pass `iterationIndex` to avoid pulling every repetition into context.\n\n---\n\n## Step 7 — Pinpoint the Root Cause\n\n### Expression Errors (e.g. `split` on null)\nIf the error mentions `InvalidTemplate` or a function name:\n1. Find the action in the definition\n2. Check what upstream action/expression it reads\n3. **Inspect that upstream action's output** for null / missing fields\n\n```python\n# Example: action uses split(item()?['Name'], ' ')\n# → null Name in the source data\nresult = mcp(\"get_live_flow_run_action_outputs\", ..., actionName=\"Compose_Names\")\nif not result:\n    print(\"No outputs returned for Compose_Names\")\n    names = []\nelse:\n    names = result[0].get(\"outputs\", {}).get(\"body\") or []\nnulls = [x for x in names if x.get(\"Name\") is None]\nprint(f\"{len(nulls)} records with null Name\")\n```\n\n### Wrong Field Path\nExpression `triggerBody()?['fieldName']` returns null → `fieldName` is wrong.\n**Inspect the trigger output** to see the actual field names:\n```python\nresult = mcp(\"get_live_flow_run_action_outputs\", ..., actionName=\"\u003ctrigger-action-name\u003e\")\nprint(json.dumps(result[0].get(\"outputs\"), indent=2)[:500])\n```\n\n### HTTP Actions Returning Errors\nThe error code says `InternalServerError` or `NotSpecified` — **always inspect\nthe action outputs** to get the actual HTTP status and response body:\n```python\nresult = mcp(\"get_live_flow_run_action_outputs\", ..., actionName=\"HTTP_Get_Data\")\nout = result[0]\nprint(f\"HTTP {out['outputs']['statusCode']}\")\nprint(json.dumps(out['outputs']['body'], indent=2)[:500])\n```\n\n### Connection / Auth Failures\nLook for `ConnectionAuthorizationFailed` — the connection owner must match the\nservice account running the flow. Cannot fix via API; fix in PA designer.\n\n### Outlook user-picker failures (`DynamicListValuesUndefinedOrInvalid`)\nOutlook actions like `GetEmailsV3` use parameters (`mailboxAddress`, `to`, `cc`,\n`from`) whose dropdown is backed by `builtInOperation:AadGraph.GetUsers` — which\nis broken at the PA listEnum layer and always returns\n`DynamicListValuesUndefinedOrInvalid`. This shows up when an agent rebuilds or\nmodifies an Outlook action via `update_live_flow` and tries to resolve a user\nthrough dynamic options. **Don't fix it by retrying AadGraph** — switch to\n`shared_office365users.SearchUserV2` instead (returns the same AAD user shape).\nUse `describe_live_connector` to confirm whether the affected parameter exposes\na structured `fallback`, then call `get_live_dynamic_options` against\n`shared_office365users.SearchUserV2` instead of the broken AadGraph operation.\nFor dynamic field schemas rather than dropdown options, use\n`get_live_dynamic_properties` with the metadata returned by\n`describe_live_connector`.\n\n---\n\n## Step 8 — Apply the Fix\n\n**For expression/data issues**:\n```python\ndefn = mcp(\"get_live_flow\", environmentName=ENV, flowName=FLOW_ID)\nacts = defn[\"properties\"][\"definition\"][\"actions\"]\n\n# Example: fix split on potentially-null Name\nacts[\"Compose_Names\"][\"inputs\"] = \\\n    \"@coalesce(item()?['Name'], 'Unknown')\"\n\nconn_refs = defn[\"properties\"][\"connectionReferences\"]\nresult = mcp(\"update_live_flow\",\n    environmentName=ENV,\n    flowName=FLOW_ID,\n    definition=defn[\"properties\"][\"definition\"],\n    connectionReferences=conn_refs)\n\nprint(result.get(\"error\"))  # None = success\n```\n\n\u003e ⚠️ `update_live_flow` always returns an `error` key.\n\u003e A value of `null` (Python `None`) means success.\n\n---\n\n## Step 9 — Verify the Fix\n\n\u003e **Use `resubmit_live_flow_run` to test ANY flow — not just HTTP triggers.**\n\u003e `resubmit_live_flow_run` replays a previous run using its original trigger\n\u003e payload. This works for **every trigger type**: Recurrence, SharePoint\n\u003e \"When an item is created\", connector webhooks, Button triggers, and HTTP\n\u003e triggers. You do NOT need to ask the user to manually trigger the flow or\n\u003e wait for the next scheduled run.\n\u003e\n\u003e The only case where `resubmit` is not available is a **brand-new flow that\n\u003e has never run** — it has no prior run to replay.\n\n```python\n# Resubmit the failed run — works for ANY trigger type\nresubmit = mcp(\"resubmit_live_flow_run\",\n    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID)\nprint(resubmit)   # {\"resubmitted\": true, \"triggerName\": \"...\"}\n\n# Wait ~30 s then check\nimport time; time.sleep(30)\nnew_runs = mcp(\"get_live_flow_runs\", environmentName=ENV, flowName=FLOW_ID, top=3)\nprint(new_runs[0][\"status\"])   # Succeeded = done\n```\n\n### When to use resubmit vs trigger\n\n| Scenario | Use | Why |\n|---|---|---|\n| **Testing a fix** on any flow | `resubmit_live_flow_run` | Replays the exact trigger payload that caused the failure — best way to verify |\n| Recurrence / scheduled flow | `resubmit_live_flow_run` | Cannot be triggered on demand any other way |\n| SharePoint / connector trigger | `resubmit_live_flow_run` | Cannot be triggered without creating a real SP item |\n| HTTP trigger with **custom** test payload | `trigger_live_flow` | When you need to send different data than the original run |\n| Brand-new flow, never run | `trigger_live_flow` (HTTP only) | No prior run exists to resubmit |\n\n### Testing HTTP-Triggered Flows with custom payloads\n\nFor flows with a `Request` (HTTP) trigger, use `trigger_live_flow` when you\nneed to send a **different** payload than the original run:\n\n```python\n# First inspect what the trigger expects — read directly from the flow definition\ndefn = mcp(\"get_live_flow\", environmentName=ENV, flowName=FLOW_ID)\ntriggers = defn[\"properties\"][\"definition\"][\"triggers\"]\nmanual = next(iter(triggers.values()))   # usually the only trigger on HTTP flows\nrequest_schema = manual.get(\"inputs\", {}).get(\"schema\")\nprint(\"Expected body schema:\", request_schema)\n\n# Response schemas live on Response action(s) in the actions block\nfor name, act in defn[\"properties\"][\"definition\"][\"actions\"].items():\n    if act.get(\"type\") == \"Response\":\n        print(f\"Response {name}:\", act.get(\"inputs\", {}).get(\"schema\"))\n\n# Trigger with a test payload\nresult = mcp(\"trigger_live_flow\",\n    environmentName=ENV,\n    flowName=FLOW_ID,\n    body={\"name\": \"Test User\", \"value\": 42})\nprint(f\"Status: {result['responseStatus']}, Body: {result.get('responseBody')}\")\n```\n\n\u003e `trigger_live_flow` handles AAD-authenticated triggers automatically.\n\u003e Only works for flows with a `Request` (HTTP) trigger type.\n\n---\n\n## Quick-Reference Diagnostic Decision Tree\n\n| Symptom | First Tool | Then ALWAYS Call | What to Look For |\n|---|---|---|---|\n| Flow shows as Failed | `get_live_flow_run_error` | `get_live_flow_run_action_outputs` on the failing action | HTTP status + response body in `outputs` |\n| Error code is generic (`ActionFailed`, `NotSpecified`) | — | `get_live_flow_run_action_outputs` | The `outputs.body` contains the real error message, stack trace, or API error |\n| HTTP action returns 500 | — | `get_live_flow_run_action_outputs` | `outputs.statusCode` + `outputs.body` with server error detail |\n| Expression crash | — | `get_live_flow_run_action_outputs` on prior action | null / wrong-type fields in output body |\n| Flow never starts | `get_live_flow` | — | check `properties.state` = \"Started\" |\n| Action returns wrong data | `get_live_flow_run_action_outputs` | — | actual output body vs expected |\n| Fix applied but still fails | `get_live_flow_runs` after resubmit | — | new run `status` field |\n\n\u003e **Rule: never diagnose from error codes alone.** `get_live_flow_run_error`\n\u003e identifies the failing action. `get_live_flow_run_action_outputs` reveals\n\u003e the actual cause. Always call both.\n\n---\n\n## Reference Files\n\n- [common-errors.md](references/common-errors.md) — Error codes, likely causes, and fixes\n- [debug-workflow.md](references/debug-workflow.md) — Full decision tree for complex failures\n\n## Related Skills\n\n- `flowstudio-power-automate-mcp` — Foundation skill: connection setup, MCP helper, tool discovery\n- `flowstudio-power-automate-build` — Build and deploy new flows\n","references/common-errors.md":"# FlowStudio MCP — Common Power Automate Errors\n\nReference for error codes, likely causes, and recommended fixes when debugging\nPower Automate flows via the FlowStudio MCP server.\n\n---\n\n## Expression / Template Errors\n\n### `InvalidTemplate` — Function Applied to Null\n\n**Full message pattern**: `\"Unable to process template language expressions... function 'split' expects its first argument 'text' to be of type string\"`\n\n**Root cause**: An expression like `@split(item()?['Name'], ' ')` received a null value.\n\n**Diagnosis**:\n1. Note the action name in the error message\n2. Call `get_live_flow_run_action_outputs` on the action that produces the array\n3. Find items where `Name` (or the referenced field) is `null`\n\n**Fixes**:\n```\nBefore: @split(item()?['Name'], ' ')\nAfter:  @split(coalesce(item()?['Name'], ''), ' ')\n\nOr guard the whole foreach body with a condition:\n  expression: \"@not(empty(item()?['Name']))\"\n```\n\n---\n\n### `InvalidTemplate` — Wrong Expression Path\n\n**Full message pattern**: `\"Unable to process template language expressions... 'triggerBody()?['FieldName']' is of type 'Null'\"`\n\n**Root cause**: The field name in the expression doesn't match the actual payload schema.\n\n**Diagnosis**:\n```python\n# Check trigger output shape\nmcp(\"get_live_flow_run_action_outputs\",\n    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID,\n    actionName=\"\u003ctrigger-name\u003e\")\n# Compare actual keys vs expression\n```\n\n**Fix**: Update expression to use the correct key name. Common mismatches:\n- `triggerBody()?['body']` vs `triggerBody()?['Body']` (case-sensitive)\n- `triggerBody()?['Subject']` vs `triggerOutputs()?['body/Subject']`\n\n---\n\n### `InvalidTemplate` — Type Mismatch\n\n**Full message pattern**: `\"... expected type 'Array' but got type 'Object'\"`\n\n**Root cause**: Passing an object where the expression expects an array (e.g. a single item HTTP response vs a list response).\n\n**Fix**:\n```\nBefore: @outputs('HTTP')?['body']\nAfter:  @outputs('HTTP')?['body/value']    ← for OData list responses\n        @createArray(outputs('HTTP')?['body'])  ← wrap single object in array\n```\n\n---\n\n## Connection / Auth Errors\n\n### `ConnectionAuthorizationFailed`\n\n**Full message**: `\"The API connection ... is not authorized.\"`\n\n**Root cause**: The connection referenced in the flow is owned by a different\nuser/service account than the one whose JWT is being used.\n\n**Diagnosis**: Check `properties.connectionReferences` — the `connectionName` GUID\nidentifies the owner. Cannot be fixed via API.\n\n**Fix options**:\n1. Open flow in Power Automate designer → re-authenticate the connection\n2. Use a connection owned by the service account whose token you hold\n3. Share the connection with the service account in PA admin\n\n---\n\n### `InvalidConnectionCredentials`\n\n**Root cause**: The underlying OAuth token for the connection has expired or\nthe user's credentials changed.\n\n**Fix**: Owner must sign in to Power Automate and refresh the connection.\n\n---\n\n## HTTP Action Errors\n\n### `ActionFailed` — HTTP 4xx/5xx\n\n**Full message pattern**: `\"An HTTP request to... failed with status code '400'\"`\n\n**Diagnosis**:\n```python\nactions_out = mcp(\"get_live_flow_run_action_outputs\", ..., actionName=\"HTTP_My_Call\")\nitem = actions_out[0]   # first entry in the returned array\nprint(item[\"outputs\"][\"statusCode\"])   # 400, 401, 403, 500...\nprint(item[\"outputs\"][\"body\"])         # error details from target API\n```\n\n**Common causes**:\n- 401 — missing or expired auth header\n- 403 — permission denied on target resource\n- 404 — wrong URL / resource deleted\n- 400 — malformed JSON body (check expression that builds the body)\n\n---\n\n### `ActionFailed` — HTTP Timeout\n\n**Root cause**: Target endpoint did not respond within the connector's timeout\n(default 90 s for HTTP action).\n\n**Fix**: Add retry policy to the HTTP action, or split the payload into smaller\nbatches to reduce per-request processing time.\n\n---\n\n## Control Flow Errors\n\n### `ActionSkipped` Instead of Running\n\n**Root cause**: The `runAfter` condition wasn't met. E.g. an action set to\n`runAfter: { \"Prev\": [\"Succeeded\"] }` won't run if `Prev` failed or was skipped.\n\n**Diagnosis**: Check the preceding action's status. Deliberately skipped\n(e.g. inside a false branch) is intentional — unexpected skip is a logic gap.\n\n**Fix**: Add `\"Failed\"` or `\"Skipped\"` to the `runAfter` status array if the\naction should run on those outcomes too.\n\n---\n\n### Foreach Runs in Wrong Order / Race Condition\n\n**Root cause**: `Foreach` without `operationOptions: \"Sequential\"` runs\niterations in parallel, causing write conflicts or undefined ordering.\n\n**Fix**: Add `\"operationOptions\": \"Sequential\"` to the Foreach action.\n\n---\n\n### Foreach Parent Failed After Handled Inner Failure\n\n**Symptom**: Inner actions have failure handlers, but the parent `Foreach` still\nshows `Failed`, and downstream actions such as `Response` are skipped.\n\n**Root cause**: A handled child failure can still mark the loop container as\nfailed. Downstream `runAfter` that only accepts `Succeeded` will not run.\n\n**Diagnosis**: Inspect the parent foreach with `get_live_flow_run_error`, then\ninspect child action outputs for the iteration that failed.\n\n**Fix**: If partial success is acceptable, allow the downstream join/response to\nrun after `Succeeded` and `Failed`, and include an explicit error summary in the\npayload. If the loop must be all-or-nothing, wrap risky inner work in a Scope and\nhandle success/failure at the Scope boundary.\n\n---\n\n## Update / Deploy Errors\n\n### `update_live_flow` Returns No-Op\n\n**Symptom**: `result[\"updated\"]` is empty list or `result[\"created\"]` is empty.\n\n**Likely cause**: Passing wrong parameter name. The required key is `definition`\n(object), not `flowDefinition` or `body`.\n\n---\n\n### `update_live_flow` — `\"Supply connectionReferences\"`\n\n**Root cause**: The definition contains `OpenApiConnection` or\n`OpenApiConnectionWebhook` actions but `connectionReferences` was not passed.\n\n**Fix**: Fetch the existing connection references with `get_live_flow` and pass\nthem as the `connectionReferences` argument.\n\n---\n\n## Data Logic Errors\n\n### `union()` Overriding Correct Records with Nulls\n\n**Symptom**: After merging two arrays, some records have null fields that existed\nin one of the source arrays.\n\n**Root cause**: `union(old_data, new_data)` — `union()` first-wins, so old_data\nvalues override new_data for matching records.\n\n**Fix**: Swap argument order: `union(new_data, old_data)`\n\n```\nBefore: @sort(union(outputs('Old_Array'), body('New_Array')), 'Date')\nAfter:  @sort(union(body('New_Array'), outputs('Old_Array')), 'Date')\n```\n\n---\n\n### Null Cascade in Filter Array / Query\n\n**Symptom**: A lookup/filter step returns the wrong record or a later expression\nfails on null even though the filter action itself succeeded.\n\n**Root cause**: The lookup key is null or empty. A condition such as\n`equals(item()?['Email'], outputs('Lookup_Email'))` can accidentally match rows\nwhere both sides are null, or can pass an empty array downstream.\n\n**Diagnosis**: Inspect the action that creates the lookup key and the filter\noutput length. Confirm the key is non-empty before trusting the filter result.\n\n**Fix**: Add a non-empty guard before the filter, normalize comparison values\nwith `trim()`/`toLower()`, and branch explicitly when no match is found.\n","references/debug-workflow.md":"# FlowStudio MCP — Debug Workflow\n\nEnd-to-end decision tree for diagnosing Power Automate flow failures.\n\n---\n\n## Top-Level Decision Tree\n\n```\nFlow is failing\n│\n├── Flow never starts / no runs appear\n│   └── ► Check flow State: get_live_flow → properties.state\n│       ├── \"Stopped\" → flow is disabled; enable in PA designer\n│       └── \"Started\" + no runs → trigger condition not met (check trigger config)\n│\n├── Flow run shows \"Failed\"\n│   ├── Step A: get_live_flow_run_error  → read error.code + error.message\n│   │\n│   ├── error.code = \"InvalidTemplate\"\n│   │   └── ► Expression error (null value, wrong type, bad path)\n│   │       └── See: Expression Error Workflow below\n│   │\n│   ├── error.code = \"ConnectionAuthorizationFailed\"\n│   │   └── ► Connection owned by different user; fix in PA designer\n│   │\n│   ├── error.code = \"ActionFailed\" + message mentions HTTP\n│   │   └── ► See: HTTP Action Workflow below\n│   │\n│   ├── parent action is Foreach / Apply to each\n│   │   └── ► Inspect child actions; handled child failures can still fail the parent\n│   │\n│   └── Unknown / generic error\n│       └── ► Walk actions backwards (Step B below)\n│\n└── Flow Succeeds but output is wrong\n    └── ► Inspect intermediate actions with get_live_flow_run_action_outputs\n        └── See: Data Quality Workflow below\n```\n\n---\n\n## Expression Error Workflow\n\n```\nInvalidTemplate error\n│\n├── 1. Read error.message — identifies the action name and function\n│\n├── 2. Get flow definition: get_live_flow\n│   └── Find that action in definition[\"actions\"][action_name][\"inputs\"]\n│       └── Identify what upstream value the expression reads\n│\n├── 3. get_live_flow_run_action_outputs for the action BEFORE the failing one\n│   └── Look for null / wrong type in that action's output\n│       ├── Null string field → wrap with coalesce(): @coalesce(field, '')\n│       ├── Null object → add empty check condition before the action\n│       └── Wrong field name → correct the key (case-sensitive)\n│\n└── 4. Apply fix with update_live_flow, then resubmit\n```\n\n---\n\n## HTTP Action Workflow\n\n```\nActionFailed on HTTP action\n│\n├── 1. get_live_flow_run_action_outputs on the HTTP action\n│   └── Read: outputs.statusCode, outputs.body\n│\n├── statusCode = 401\n│   └── ► Auth header missing or expired OAuth token\n│       Check: action inputs.authentication block\n│\n├── statusCode = 403\n│   └── ► Insufficient permission on target resource\n│       Check: service principal / user has access\n│\n├── statusCode = 400\n│   └── ► Malformed request body\n│       Check: action inputs.body expression; parse errors often in nested JSON\n│\n├── statusCode = 404\n│   └── ► Wrong URL or resource deleted/renamed\n│       Check: action inputs.uri expression\n│\n└── statusCode = 500 / timeout\n    └── ► Target system error; retry policy may help\n        Add: \"retryPolicy\": {\"type\": \"Fixed\", \"count\": 3, \"interval\": \"PT10S\"}\n```\n\n---\n\n## Data Quality Workflow\n\n```\nFlow succeeds but output data is wrong\n│\n├── 1. Identify the first \"wrong\" output — which action produces it?\n│\n├── 2. get_live_flow_run_action_outputs on that action\n│   └── Compare actual output body vs expected\n│\n├── Source array has nulls / unexpected values\n│   ├── Check the trigger data — get_live_flow_run_action_outputs on trigger\n│   └── Trace forward action by action until the value corrupts\n│\n├── Merge/union has wrong values\n│   └── Check union argument order:\n│       union(NEW, old) = new wins  ✓\n│       union(OLD, new) = old wins  ← common bug\n│\n├── Foreach output missing items\n│   ├── Check foreach condition — filter may be too strict\n│   └── Check if parallel foreach caused race condition (add Sequential)\n│\n├── Filter/Query result unexpectedly matches nulls or returns empty\n│   └── Guard lookup keys before the filter; do not compare null-to-null\n│\n└── Date/time values wrong timezone\n    └── Use convertTimeZone() — utcNow() is always UTC\n```\n\n---\n\n## Walk-Back Analysis (Unknown Failure)\n\nWhen the error message doesn't clearly name a root cause:\n\n```python\n# 1. Get all action names from definition\ndefn = mcp(\"get_live_flow\", environmentName=ENV, flowName=FLOW_ID)\nactions = list(defn[\"properties\"][\"definition\"][\"actions\"].keys())\n\n# 2. Check status of each action in the failed run\nfor action in actions:\n    actions_out = mcp(\"get_live_flow_run_action_outputs\",\n        environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID,\n        actionName=action)\n    # Returns an array of action objects\n    item = actions_out[0] if actions_out else {}\n    status = item.get(\"status\", \"unknown\")\n    print(f\"{action}: {status}\")\n\n# 3. Find the boundary between Succeeded and Failed/Skipped\n# The first Failed action is likely the root cause (unless skipped by design)\n```\n\nActions inside Foreach / Condition branches may appear nested —\ncheck the parent action first to confirm the branch ran at all.\n\n---\n\n## Post-Fix Verification Checklist\n\n1. `update_live_flow` returns `error: null` — definition accepted  \n2. `resubmit_live_flow_run` confirms new run started  \n3. Wait for run completion (poll `get_live_flow_runs` every 15 s)  \n4. Confirm new run `status = \"Succeeded\"`  \n5. If flow has downstream consumers (child flows, emails, SharePoint writes),\n   spot-check those too\n"},"import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/tree/541b7819d8c3545c6df122491af4fa1eae415779/plugins/flowstudio-power-automate/skills/flowstudio-power-automate-debug"}},"content_hash":[70,238,253,73,184,157,94,188,135,82,18,224,34,17,31,52,7,212,169,206,86,174,83,158,52,198,109,253,6,19,143,8],"trust_level":"unsigned","yanked":false}