awesome-copilot/skills/flowstudio-power-automate-debug/references/common-errors.md

FlowStudio MCP — Common Power Automate Errors

Reference for error codes, likely causes, and recommended fixes when debugging Power Automate flows via the FlowStudio MCP server.

---

Expression / Template Errors

InvalidTemplate — Function Applied to Null

Full message pattern: "Unable to process template language expressions... function 'split' expects its first argument 'text' to be of type string"

Root cause: An expression like @split(item()?['Name'], ' ') received a null value.

Diagnosis:

1. Note the action name in the error message
2. Call get_live_flow_run_action_outputs on the action that produces the array
3. Find items where Name (or the referenced field) is null

Fixes:

Before: @split(item()?['Name'], ' ')
After:  @split(coalesce(item()?['Name'], ''), ' ')

Or guard the whole foreach body with a condition:
  expression: "@not(empty(item()?['Name']))"

---

InvalidTemplate — Wrong Expression Path

Full message pattern: "Unable to process template language expressions... 'triggerBody()?['FieldName']' is of type 'Null'"

Root cause: The field name in the expression doesn't match the actual payload schema.

Diagnosis:

# Check trigger output shape
mcp("get_live_flow_run_action_outputs",
    environmentName=ENV, flowName=FLOW_ID, runName=RUN_ID,
    actionName="<trigger-name>")
# Compare actual keys vs expression

Fix: Update expression to use the correct key name. Common mismatches:

• triggerBody()?['body'] vs triggerBody()?['Body'] (case-sensitive)
• triggerBody()?['Subject'] vs triggerOutputs()?['body/Subject']

---

InvalidTemplate — Type Mismatch

Full message pattern: "... expected type 'Array' but got type 'Object'"

Root cause: Passing an object where the expression expects an array (e.g. a single item HTTP response vs a list response).

Fix:

Before: @outputs('HTTP')?['body']
After:  @outputs('HTTP')?['body/value']    ← for OData list responses
        @createArray(outputs('HTTP')?['body'])  ← wrap single object in array

---

Connection / Auth Errors

ConnectionAuthorizationFailed

Full message: "The API connection ... is not authorized."

Root cause: The connection referenced in the flow is owned by a different user/service account than the one whose JWT is being used.

Diagnosis: Check properties.connectionReferences — the connectionName GUID identifies the owner. Cannot be fixed via API.

Fix options:

1. Open flow in Power Automate designer → re-authenticate the connection
2. Use a connection owned by the service account whose token you hold
3. Share the connection with the service account in PA admin

---

InvalidConnectionCredentials

Root cause: The underlying OAuth token for the connection has expired or the user's credentials changed.

Fix: Owner must sign in to Power Automate and refresh the connection.

---

HTTP Action Errors

ActionFailed — HTTP 4xx/5xx

Full message pattern: "An HTTP request to... failed with status code '400'"

Diagnosis:

actions_out = mcp("get_live_flow_run_action_outputs", ..., actionName="HTTP_My_Call")
item = actions_out[0]   # first entry in the returned array
print(item["outputs"]["statusCode"])   # 400, 401, 403, 500...
print(item["outputs"]["body"])         # error details from target API

Common causes:

• 401 — missing or expired auth header
• 403 — permission denied on target resource
• 404 — wrong URL / resource deleted
• 400 — malformed JSON body (check expression that builds the body)

---

ActionFailed — HTTP Timeout

Root cause: Target endpoint did not respond within the connector's timeout (default 90 s for HTTP action).

Fix: Add retry policy to the HTTP action, or split the payload into smaller batches to reduce per-request processing time.

---

Control Flow Errors

ActionSkipped Instead of Running

Root cause: The runAfter condition wasn't met. E.g. an action set to runAfter: { "Prev": ["Succeeded"] } won't run if Prev failed or was skipped.

Diagnosis: Check the preceding action's status. Deliberately skipped (e.g. inside a false branch) is intentional — unexpected skip is a logic gap.

Fix: Add "Failed" or "Skipped" to the runAfter status array if the action should run on those outcomes too.

---

Foreach Runs in Wrong Order / Race Condition

Root cause: Foreach without operationOptions: "Sequential" runs iterations in parallel, causing write conflicts or undefined ordering.

Fix: Add "operationOptions": "Sequential" to the Foreach action.

---

Foreach Parent Failed After Handled Inner Failure

Symptom: Inner actions have failure handlers, but the parent Foreach still shows Failed, and downstream actions such as Response are skipped.

Root cause: A handled child failure can still mark the loop container as failed. Downstream runAfter that only accepts Succeeded will not run.

Diagnosis: Inspect the parent foreach with get_live_flow_run_error, then inspect child action outputs for the iteration that failed.

Fix: If partial success is acceptable, allow the downstream join/response to run after Succeeded and Failed, and include an explicit error summary in the payload. If the loop must be all-or-nothing, wrap risky inner work in a Scope and handle success/failure at the Scope boundary.

---

Update / Deploy Errors

update_live_flow Returns No-Op

Symptom: result["updated"] is empty list or result["created"] is empty.

Likely cause: Passing wrong parameter name. The required key is definition (object), not flowDefinition or body.

---

update_live_flow — "Supply connectionReferences"

Root cause: The definition contains OpenApiConnection or OpenApiConnectionWebhook actions but connectionReferences was not passed.

Fix: Fetch the existing connection references with get_live_flow and pass them as the connectionReferences argument.

---

Data Logic Errors

union() Overriding Correct Records with Nulls

Symptom: After merging two arrays, some records have null fields that existed in one of the source arrays.

Root cause: union(old_data, new_data) — union() first-wins, so old_data values override new_data for matching records.

Fix: Swap argument order: union(new_data, old_data)

Before: @sort(union(outputs('Old_Array'), body('New_Array')), 'Date')
After:  @sort(union(body('New_Array'), outputs('Old_Array')), 'Date')

---

Null Cascade in Filter Array / Query

Symptom: A lookup/filter step returns the wrong record or a later expression fails on null even though the filter action itself succeeded.

Root cause: The lookup key is null or empty. A condition such as equals(item()?['Email'], outputs('Lookup_Email')) can accidentally match rows where both sides are null, or can pass an empty array downstream.

Diagnosis: Inspect the action that creates the lookup key and the filter output length. Confirm the key is non-empty before trusting the filter result.

Fix: Add a non-empty guard before the filter, normalize comparison values with trim()/toLower(), and branch explicitly when no match is found.