@uipath/skills 1.204.0 → 1.204.1

package/skills/uipath-maestro-flow/references/diagnose/failure-modes.md

@@ -0,0 +1,353 @@
+# Failure Modes — Pattern Catalog
+
+Lookup table for known recurring failure modes in Maestro Flow projects. Each entry: what the failure looks like, why it happens, how to fix it, where to read more. Use this when you have an error symptom in hand and want to identify the pattern.
+
+> **Hot-path triage:** if you have a failed run and need to investigate from scratch, start at [troubleshooting-guide.md](troubleshooting-guide.md) (the priority ladder: incidents → variables → flow correlation → traces). This document is the **lookup catalog** — read it after the ladder identifies a known pattern, or when the symptom matches an entry below.
+
+## Index
+
+| Pattern | Symptom | Cause |
+|---|---|---|
+| [`=js:` prefix missing](#js-prefix-missing) | Activity input bound to literal string `"vars.X.output.Y"` | Missing `=js:` prefix on a `$vars` reference. `flow validate` catches this — pre-`expression-prefix-validator` cli still ships the literal at runtime. |
+| [`variables.nodes[]` missing](#variablesnodes-missing--varsxoutput-resolves-to-undefined) | `Cannot read property 'output' of undefined` on a downstream node | Direct-authored `.flow` skipped `variables.nodes[]`; `flow validate` accepts it but the BPMN has no process-level variable declaration for the upstream node. |
+| [Misshapen nodes in Studio Web](#misshapen-rectangle-nodes-in-studio-web) | Nodes render at the wrong size for their shape | `flow format` not run before publish |
+| [HITL outcome port unwired](#hitl-outcome-port-unwired) | Flow hangs indefinitely after a HITL node | No outgoing edge from one of the node's `outcome-<outcome.id>` source ports |
+| [Run reports `Completed`, work not done](#run-reports-completed-but-the-work-never-happened) | Run finishes `Completed`, but the API call / node it depended on failed | `inputs.errorHandlingEnabled: true` on a node with no handler, or an `error` edge routed back into the happy path |
+| [Reused reference ID](#reused-reference-id--cross-connection-id-leakage) | Connector node faults silently at runtime | Reference ID copied from a prior flow's connection |
+| [Single-nested layout](#single-nested-layout) | Studio Web upload fails; `flow init` auto-registration is skipped | `uip maestro flow init` was run with `--skip-solution-registration` (opts out of auto-scaffold + registration) |
+| [Missing `bindings[]` on resource node](#missing-bindings-on-resource-node) | `Folder does not exist or the user does not have access to the folder` | Top-level `bindings[]` entries not added for a `uipath.core.*` resource node |
+| [`flow validate` passes, `flow debug` faults](#flow-validate-passes-flow-debug-faults) | Local validation green, cloud run red | Multiple causes — narrower than before (the missing-`=js:` validator + expression-ref linting now catch a large slice statically). See entry for the residual triage path. |
+
+---
+
+## `=js:` prefix missing
+
+### Symptom
+
+A connector, HTTP, or end node receives the literal string `"vars.X.output.Y"` as its input value at runtime instead of the resolved value.
+
+`flow validate` flags this as an error today (cli-side `expression-prefix-validator`, emitted with a remediation hint pointing at the `=js:`-prefixed form). Pre-validator cli versions miss it and the failure surfaces only at `flow debug` or in deployed runs — if you see the symptom without a corresponding validate error, your cli is older than the fix.
+
+Example: input field set to literal `"vars.createEntityRecord1.output.Id"` instead of the entity's actual ID.
+
+### Cause
+
+The `=js:` prefix was omitted on a `$vars` / `$metadata` / `$self` reference inside a value field. The serializer rewrites `$vars` → `vars` whether or not the prefix is present, so a missing `=js:` yields a string that **looks like** an unevaluated expression but is actually a literal.
+
+There is also no `nodes.X.output.Y` syntax — that is an invented form that silently ships as a literal string. `flow validate` flags this same way (rewriting the suggested fix to the `=js:$vars.X.output.Y` form).
+
+### Fix
+
+Add `=js:` to every `$vars`/`$metadata`/`$self` reference in:
+
+- Connector `inputs.detail.bodyParameters` / `queryParameters` / `pathParameters`
+- HTTP `url` / `headers` / `body`
+- End node output `source`
+- Variable update `expression`
+- Loop `collection`
+- Subflow `inputs.<id>.source`
+
+Do **not** add `=js:` to condition expressions (decision `expression`, switch case `expression`, HTTP branch `conditionExpression`) — those are evaluated as JavaScript automatically.
+
+### Reference
+
+[shared/node-output-wiring.md](../shared/node-output-wiring.md) — canonical per-node-type field reference.
+
+---
+
+## `variables.nodes[]` missing → `$vars.X.output` resolves to undefined
+
+### Symptom
+
+A downstream script or expression reads `$vars.<sourceNodeId>.output` and gets `undefined` at runtime. Common shapes: `Cannot read property 'output' of undefined`, `Cannot read properties of undefined (reading '<field>')`, or a connector activity receiving an empty / undefined input that an upstream node should have populated. `uip maestro flow validate` accepts the file without complaint. The upstream node's own incident shows it ran successfully.
+
+### Cause
+
+The `.flow` file is missing `variables.nodes[]` entries for the upstream node. The BPMN emitter walks `variables.nodes[]` to write the process-level `<uipath:inputOutput id="<nodeId>.<outputId>">` declarations the runtime needs — without them, the activity's local `output` value has no process variable to flow into, and downstream `$vars` reads fail.
+
+This happens almost exclusively on **direct-authored** `.flow` files: `uip maestro flow node add` and the canvas / Studio Web save path both auto-populate `variables.nodes[]`. `Edit` / `Write` authoring does not, and pre-fix `uip maestro flow format` did not regenerate it either. Adding an `outputs` block on the action-node instance does **not** fix this — for action nodes the BPMN emitter reads the manifest's `outputDefinition`, not the instance block, so authoring the instance block has no runtime effect.
+
+### Fix
+
+Run `uip maestro flow format <ProjectName>.flow --output json`. Current CLI versions regenerate `variables.nodes[]` from `nodes[]` + `definitions[]` (matching `node add` and canvas behavior). On older CLI versions, add the entries manually:
+
+```json
+"variables": {
+  "nodes": [
+    {
+      "id": "<nodeId>.output",
+      "type": "object",
+      "binding": { "nodeId": "<nodeId>", "outputId": "output" }
+    },
+    {
+      "id": "<nodeId>.error",
+      "type": "object",
+      "binding": { "nodeId": "<nodeId>", "outputId": "error" }
+    }
+  ]
+}
+```
+
+One entry per declared output (trigger nodes: `output` only; action nodes: `output` + `error`; end / terminate: none).
+
+### Reference
+
+[shared/file-format.md — Node outputs](../shared/file-format.md#node-outputs), [author/CAPABILITY.md rule #14](../author/CAPABILITY.md), [editing-operations-json.md — Pre-flight Checklist step 5–6](../author/editing-operations-json.md#pre-flight-checklist).
+
+---
+
+## Misshapen rectangle nodes in Studio Web
+
+### Symptom
+
+After publish or debug upload, Studio Web renders nodes at the wrong dimensions for their shape — a square/circle node stretched into an oblong (e.g., 200×80), or an inline agent squashed to a 96×96 square instead of its 288×96 rectangle. Layout looks visually broken even though the flow runs correctly.
+
+### Cause
+
+`uip maestro flow format` was not run before publishing or debugging. Hand-written or stale `layout` data with dimensions that don't match each node's shape remains in the `.flow` file and Studio Web renders it as-is.
+
+### Fix
+
+Run format before any publish or debug operation:
+
+```bash
+uip maestro flow format <ProjectName>.flow --output json
+```
+
+Format:
+
+- Sets each node's `size` by its canvas shape (inline agents → 288×96, containers → 560×320, everything else → 96×96)
+- Arranges nodes horizontally with ELK at `nodeSpacing: 96`
+- Recurses into subflows and rewrites `subflows[<id>].layout`
+- Preserves sticky note custom sizes
+
+### Reference
+
+[author capability](../author/CAPABILITY.md) — see "Always run `flow format` after edits" in critical rules; [shared/cli-commands.md — uip maestro flow format](../shared/cli-commands.md#uip-maestro-flow-format).
+
+---
+
+## HITL outcome port unwired
+
+### Symptom
+
+Flow execution reaches a HITL QuickForm node, the human task is created and completed, but the flow blocks indefinitely afterward on one or more branches. No further nodes execute on the affected branch.
+
+### Cause
+
+A QuickForm node has one output port per outcome, named `outcome-<outcome.id>`. `outcome-completed` is a separate, zero-outcome placeholder port that disappears the instant the schema has any real outcome — it is never a real branch once outcomes exist. Either one of the real outcome ports has no outgoing edge, or the flow was wired against the stale `outcome-completed` placeholder instead of the real per-outcome ports.
+
+### Fix
+
+Add an edge from each `outcome-<outcome.id>` port to its next node — every outcome the schema declares needs its own edge. After running `uip maestro flow hitl add`, always wire every outcome port before validating; see [hitl/impl.md](../author/plugins/hitl/impl.md).
+
+### Reference
+
+[Author HITL plugin reference](../author/plugins/hitl/impl.md) — full HITL node reference including port wiring requirements.
+
+---
+
+## Run reports `Completed` but the work never happened
+
+### Symptom
+
+`finalStatus` is `Completed` and no incident is raised, yet the flow's real effect is missing — the record was never created, the message never sent, the downstream node ran on empty or stale data. The flow "always looks successful," including on runs where a dependency was demonstrably down. Nothing shows up in `instance incidents` because, as far as the engine is concerned, nothing failed.
+
+### Cause
+
+The failing node has `inputs.errorHandlingEnabled: true`, which suppresses its fault instead of faulting the run. Two shapes:
+
+1. **Flag with no handler** — the flag is set on a node with no outgoing `sourcePort: "error"` edge. The node swallows the exception and execution continues down `default` with missing output.
+2. **Error path rejoins the happy path** — an `error` edge targets the next happy-path node, or reaches the same End node the success path reaches. The failure then runs the success path's output mappings against the failed node's empty output.
+
+Both pass `uip maestro flow validate` — it checks structure, never whether an error path is meaningful.
+
+### Fix
+
+Report every node carrying the flag, and where its error path ends:
+
+```bash
+python3 - "<ProjectName>.flow" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+E = d.get("edges", []); N = {n["id"]: n for n in d.get("nodes", [])}
+
+def targets(nid, port=None, exclude=None):
+    return [e["targetNodeId"] for e in E if e["sourceNodeId"] == nid
+            and (port is None or e.get("sourcePort") == port)
+            and (exclude is None or e.get("sourcePort") != exclude)]
+
+def terminals(start, seen=None):
+    seen = seen or set()
+    if start in seen: return set()
+    seen.add(start)
+    if (N.get(start) or {}).get("type") in ("core.control.end", "core.logic.terminate"):
+        return {start}
+    return set().union(*[terminals(t, seen) for t in targets(start)] or [set()])
+
+for nid, n in N.items():
+    if (n.get("inputs") or {}).get("errorHandlingEnabled") is not True: continue
+    err, ok = targets(nid, "error"), targets(nid, exclude="error")
+    if not err:
+        print(f"{nid}: flag set, NO error edge"); continue
+    ok_term = set().union(*[terminals(t) for t in ok]) if ok else set()
+    for t in err:
+        if t in ok: print(f"{nid}: error -> {t} REJOINS the happy path")
+        elif terminals(t) and terminals(t) <= ok_term:
+            print(f"{nid}: error -> {t} shares success terminal(s) {sorted(terminals(t))}")
+        else: print(f"{nid}: error -> {t} distinct terminal(s) {sorted(terminals(t))} - ok")
+PY
+```
+
+No output means no node has the flag set — the flow is clean. Otherwise act per line:
+
+- **`flag set, NO error edge`** (shape 1) — remove `inputs.errorHandlingEnabled` from that node. The failure then faults the run, which is the visible, correct outcome.
+- **`REJOINS the happy path`** / **`shares success terminal(s)`** (shape 2) — repoint the `error` edge at a terminal the caller can distinguish from success: a distinct End node mapping an error/status `out` variable, or `core.logic.terminate` when recovery is impossible.
+- **`distinct terminal(s) … - ok`** — this node's error handling is wired correctly; look elsewhere.
+
+Re-run `uip maestro flow validate` and `uip maestro flow format` after either fix.
+
+### Reference
+
+- [shared/file-format.md — Default: off](../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles) and [Do not swallow the failure](../shared/file-format.md#do-not-swallow-the-failure)
+- [Author capability — rule #16](../author/CAPABILITY.md#critical-rules)
+
+---
+
+## Reused reference ID — cross-connection ID leakage
+
+### Symptom
+
+A connector node passes `flow validate` and `node configure` cleanly. At runtime (`flow debug` or deployed run), the node faults silently with no resolvable error.
+
+Common scenarios:
+
+- A `parentFolderId` from one Outlook mailbox used in a flow connected to a different Outlook mailbox
+- A Slack channel ID from one workspace used in a flow connected to a different Slack workspace
+- A Jira project key copied from a prior session
+
+### Cause
+
+Reference IDs (mailbox folders, Slack channels, Jira projects, Google Sheets, etc.) are **scoped to the specific authenticated account behind the connection**. They are not portable across connections, even when the connection points to the same connector type.
+
+### Fix
+
+Always re-resolve reference IDs against the connection bound to the current flow. Never paste a value you saw in another flow or session:
+
+```bash
+uip is resources run list <connector-key> <objectName> --connection-id <CURRENT_CONNECTION_ID> --output json
+```
+
+### Reference
+
+- [Author connector plugin — Step 4](../author/plugins/connector/impl.md)
+- [Author connector-trigger plugin — Step 3](../author/plugins/connector-trigger/impl.md)
+
+---
+
+## Single-nested layout
+
+### Symptom
+
+`uip solution upload` rejects the project. The `.flow` file lives at `<Project>/<Project>.flow` (single-nested) instead of the required `<Solution>/<Project>/<Project>.flow` (double-nested). `flow init` returned `Data.SolutionRegistration.Status: "OptedOut"` (or `"NotInSolution"`). Studio Web upload fails with structural errors. Packaging fails.
+
+### Cause
+
+`uip maestro flow init` was run with `--skip-solution-registration`, which opts out of both auto-scaffold and registration and leaves a bare single-nested project. (Without that flag, `flow init` outside a solution now auto-scaffolds `<Project>Solution/<Project>/` and registers — `Status: Registered` — so this layout no longer happens by accident.)
+
+### Fix
+
+Delete the partial scaffold. Restart in the correct order — `flow init` from inside the solution directory will auto-register the project with the `.uipx`, so the explicit `uip solution projects add` step is no longer needed.
+
+```bash
+uip solution init "<SolutionName>" --output json
+cd <SolutionName>
+uip maestro flow init <ProjectName> --output json
+# Confirm Data.SolutionRegistration.Status is "Registered" in the JSON response.
+# Only if Status is "NotInSolution" / "Skipped" / "Failed" do you need:
+#   uip solution projects add <SolutionName>/<ProjectName> <SolutionName>/<SolutionName>.uipx
+```
+
+> **Was the broken project a Maestro Automate one?** This recipe rebuilds it, so carry `--automate` on the `flow init` above. Check before deleting: a `.maestro_automate` file in the project root means it was. Rebuilding without the flag returns a plain Flow, and nothing downstream reports the change.
+
+After running, verify the file exists at the double-nested path. The `cd <SolutionName>` above persists across Bash calls, so anchor the check with `$(pwd)` instead of repeating `<SolutionName>/`:
+
+```bash
+ls "$(pwd)/<ProjectName>/<ProjectName>.flow"
+```
+
+A relative `ls "<SolutionName>/<ProjectName>/<ProjectName>.flow"` here resolves to `<SolutionName>/<SolutionName>/<ProjectName>/<ProjectName>.flow` (triple-nested) and reports "no such file" even on a correctly-scaffolded solution — a false negative that turns a healthy layout into a fake bug.
+
+If the absolute path doesn't exist, the `init` step was wrong — do not try to patch the layout by hand.
+
+### Reference
+
+[Author greenfield journey — Step 2](../author/greenfield.md) — the canonical scaffold sequence.
+
+---
+
+## Missing `bindings[]` on resource node
+
+### Symptom
+
+`uip maestro flow validate` passes locally. At `uip maestro flow debug` (or in deployed runs), the resource node faults with:
+
+```text
+Folder does not exist or the user does not have access to the folder.
+```
+
+The error mentions a folder, but the actual cause is a missing binding entry.
+
+### Cause
+
+For `uipath.core.*` resource nodes (rpa, agent, flow, agentic-process, api-workflow, hitl), the registry definition carries `model.context[]` with `<bindings.{name}>` placeholders. The runtime rewrites these to `=bindings.{id}` at BPMN emit by matching `(resourceKey, name)` against the **top-level `bindings[]` array** in the `.flow` file. Without those entries, the placeholder never resolves and the runtime treats the binding as missing — surfacing as the folder-not-found error.
+
+`flow validate` checks JSON schema and cross-references; it does not validate that resource-node `model.context[]` entries are matched by top-level `bindings[]` entries.
+
+### Fix
+
+Add two entries to the top-level `bindings[]` array per resource node — `name` and `folderPath` — with `resourceKey` matching the definition's `model.bindings.resourceKey`. See the relevant resource plugin's `impl.md` for the exact shape ([rpa](../author/plugins/rpa/impl.md), [agent](../author/plugins/agent/impl.md), [flow](../author/plugins/flow/impl.md), [agentic-process](../author/plugins/agentic-process/impl.md), [api-workflow](../author/plugins/api-workflow/impl.md), [hitl](../author/plugins/hitl/impl.md)).
+
+### Reference
+
+[shared/file-format.md — Bindings](../shared/file-format.md#bindings--orchestrator-resource-bindings-top-level-bindings)
+
+---
+
+## `flow validate` passes, `flow debug` faults
+
+### Symptom
+
+Local `uip maestro flow validate` returns `Result: Success`. The same flow fails at `uip maestro flow debug` with a runtime error.
+
+### Cause
+
+Multiple. `flow validate` runs a JSON schema check, cross-reference checks, expression-reference linting, and a small set of structural rules.
+
+**Caught** (each with a precise field path and remediation hint). **Error** severity exits non-zero; **warning** severity still exits **0**, so read `Data.Warnings` rather than the exit code:
+
+- Missing `=js:` prefix on `$vars`/`$metadata`/`$self` — emitted by cli-side `expression-prefix-validator`
+- Invented `nodes.<id>.output.<...>` syntax (same failure class) — same validator, suggests `=js:$vars.<id>.output.<...>` as the fix
+- References to unknown variable IDs or node IDs in `=js:` expressions (`EXPR_UNRESOLVED_REF`) — flow-schema `expression-ref` rule
+- Output-path walks that descend into a declared primitive (`type: "string"` etc.) or a schema closed with `additionalProperties: false` (`EXPR_INVALID_OUTPUT_PATH`) — flow-schema `expression-ref` rule
+- Missing End-node output mappings for declared `out` variables (`MISSING_OUTPUT_MAPPING`, **warning** severity) — flow-schema `output-mapping` rule
+- A `$vars.<nodeId>` read whose node is not in the reader's scope (`EXPRESSION_DIAGNOSTIC`, **warning** severity). The message prints the scope it *is* in: `Property '<nodeId>' does not exist on type '{ … }'`. Never ship it, but diagnose the runtime symptom from *why* the node is out of scope, because the three causes do not behave alike: a Decision or Switch is unreadable from anywhere downstream and reads `undefined`, silently yielding a wrong result instead of faulting ([decision/impl.md — Outputs](../author/plugins/decision/impl.md#outputs)); a node that runs *after* the reader faults instead, with `[400302]`/`[400300]` ([brownfield.md — Common edits](../author/brownfield.md#common-edits)); a node on a branch the reader is not on reads `undefined`, having never executed
+- Connector `inputs.detail.configuration` missing, empty, missing the `essentialConfiguration` envelope, or containing invalid JSON inside the `=jsonString:` prefix — emitted with a shape hint pointing at `uip maestro flow node configure`. Re-run that command rather than hand-editing.
+- A non-catalog activity node (`uipath.connector.custom.*`) without `inputs.inlineActivityConfiguration`, a `scriptRef` (main or lookup) with no script under `scripts`, or an `activityContext` whose `source` is not `"inline"` / whose `scriptRef` differs from the embedded one — `inline-activity` validator. Re-add the node with `node add --metadata --scripts`, or re-run `node configure`; see [connector/impl-inline.md — Validate](../author/plugins/connector/impl-inline.md#validate).
+
+**Not caught** — these still surface only at `flow debug` or in deployed runs:
+
+- Reused reference IDs → see [Reused reference ID](#reused-reference-id--cross-connection-id-leakage)
+- Missing top-level `bindings[]` entries on resource nodes → see [Missing `bindings[]` on resource node](#missing-bindings-on-resource-node)
+- HITL outcome port unwired → see [HITL outcome port unwired](#hitl-outcome-port-unwired)
+- Stale `layout` data → see [Misshapen rectangle nodes](#misshapen-rectangle-nodes-in-studio-web) (cosmetic, not faulting)
+- Output-path walks against **open** output schemas — HTTP response bodies, script returns, free-text agent output. The deep-path walker is permissive by design: it skips when the producer's schema doesn't authoritatively declare the field's structure, so e.g. `=js:$vars.fetchWeather.output.body.current_weather` against an HTTP node that declares only `output: { type: "object" }` passes validate and faults only when the runtime response doesn't have that path.
+- Wrong-direction reads (reading an `out`-only variable) — currently a runtime concern; the direction discriminator isn't yet threaded into the validator context.
+
+### Fix
+
+Triage via the diagnostic priority ladder in [troubleshooting-guide.md](troubleshooting-guide.md). Match the incident message and faulting element to the patterns above.
+
+### Reference
+
+[troubleshooting-guide.md](troubleshooting-guide.md) — start there for any "passes locally, fails in cloud" scenario.

package/skills/uipath-maestro-flow/references/diagnose/troubleshooting-guide.md

@@ -0,0 +1,174 @@
+# Troubleshooting Failed Flows
+
+Diagnostic workflow for failed debug runs and deployed process runs. All commands require `uip login`.
+
+> **`--folder-key` is required.** All `instance` and `incident get` commands require `--folder-key <FOLDER_KEY>`. Get the folder key from `uip or folders list --output json` or from the job/process context.
+
+## Diagnostic priority
+
+Investigate in this order — each step adds context, stop when you have enough to diagnose the root cause:
+
+0. The failed `flow debug` response you already have (incident + fault detail, no extra call)
+1. Incidents (error message + faulting element)
+2. Runtime variables (data state at failure)
+3. Flow definition correlation (map element to `.flow` node)
+4. Traces (last resort — verbose full timeline)
+
+## Step 0 — Read the cause in the debug output you already have
+
+A faulted `uip maestro flow debug` response already carries the incident and the fault detail. **Do not re-run `flow debug` before you read them.** An unchanged re-run re-uploads the solution and repeats the same fault against real systems.
+
+The response can exceed 200,000 characters. `"Result": "Failure"` and `Context.ErrorCode` (the numeric incident code) sit in the first 1,000 characters; the cause sits tens of thousands of characters deeper. Reading the head of the output and stopping tells you that the run failed, not why. Never report a faulted run as "incomplete" — report the fault code and the detail.
+
+Two fields hold the cause:
+
+| Field | JSON path |
+|---|---|
+| Fault code + faulting element | `Data.incidents[].dependentFaultCode`, `.elementId`, `.errorCode`, `.errorDetails` |
+| Fault detail (the real message) | `Data.variables.elements[].outputs.Error.detail`, `.code` |
+
+### Redirect stdout to a file, then extract
+
+Logs go to stderr and JSON to stdout, so redirect stdout to keep the full response. Keep stderr visible — on a poll-budget overrun it carries the only instanceId (see [cli-conventions.md §7](../shared/cli-conventions.md#7-use-uip_log_levelinfo-for-debug-runs)).
+
+```bash
+UIP_LOG_LEVEL=info uip maestro flow debug <PROJECT_DIR> --output json > /tmp/flow-debug.json
+```
+
+Wait for the process to exit before reading the file. `flow debug` prints its JSON only when it exits, so an empty file means the run is still going — see [operate/run.md — Debug](../operate/run.md#debug--controlled-end-to-end-run).
+
+Extract both fields:
+
+```bash
+jq -r '.Data.incidents[] | "\(.elementId) \(.errorCode) \(.dependentFaultCode) \(.errorDetails)"' /tmp/flow-debug.json
+jq -r '.Data.variables.elements[] | select(.outputs.Error) | "\(.elementId) \(.outputs.Error.code) \(.outputs.Error.detail)"' /tmp/flow-debug.json
+```
+
+Without `jq`:
+
+```bash
+python3 - /tmp/flow-debug.json <<'EOF'
+import json, sys
+data = json.load(open(sys.argv[1]))["Data"]
+for incident in data.get("incidents", []):
+    print(incident["elementId"], incident["errorCode"], incident["dependentFaultCode"], incident["errorDetails"])
+for element in data.get("variables", {}).get("elements", []):
+    error = element.get("outputs", {}).get("Error")
+    if error:
+        print(element["elementId"], error["code"], error["detail"])
+EOF
+```
+
+The CLI applies `--output-filter` only when a command succeeds; a faulted run prints the whole envelope.
+
+### Match the fault code
+
+Match `dependentFaultCode`, or the failure marker on a run that never started, to a known cause:
+
+| Fault marker | Cause and fix |
+|---|---|
+| `dependentFaultCode: AGENT_STARTUP.INPUT_VALIDATION_ERROR` | Declared `type` does not match the bound node's real output shape — the runtime strict-validates agent inputs. `detail` names the failing key and the real type (for example `input_type=list`). See [author/plugins/inline-agent/impl.md — Anti-patterns](../author/plugins/inline-agent/impl.md#anti-patterns). |
+| `Stage: prepare-custom-debug` with `HttpStatus: 500`, and no `Data.incidents` | Debug was pointed at a shared folder with `--folder-path` or `--folder-key`. The server fails to prepare the run and no instance starts, so there is no incident to read. Re-run `flow debug` without the flag. See [operate/run.md — Debug](../operate/run.md#debug--controlled-end-to-end-run). |
+
+No match, or `detail` is not enough → `uip maestro flow debug-instance incidents <INSTANCE_ID> --output json` returns the full backend payload (incidentId, errorDetails, AI summary). For a deployed process run, continue with Step 1.
+
+## Step 1 — Get the instance ID
+
+The debug output (`Data.instanceId`) or `job status` response contains the instance ID. If you only have a job key:
+
+```bash
+uip maestro flow job status <JOB_KEY> --output json
+```
+
+Parse the instance ID and folder key from the response.
+
+## Step 2 — Fetch incidents
+
+Failed flows always have an incident. Start here — incidents give you the error category, message, and the faulting element.
+
+```bash
+uip maestro flow instance incidents <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Drill into a specific incident for full detail:
+
+```bash
+uip maestro flow incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+To get a cross-process incident overview:
+
+```bash
+uip maestro flow incident summary --output json
+```
+
+## Step 3 — Fetch runtime variable state
+
+Get the variable values at the time of failure to understand what data each node was working with:
+
+```bash
+uip maestro flow instance variables <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Scope to a specific element (node or subflow):
+
+```bash
+uip maestro flow instance variables <INSTANCE_ID> --folder-key <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json
+```
+
+## Step 4 — Correlate with the flow definition
+
+Use the incident's faulting element ID and the variable state to locate the failure point in the `.flow` file. Map the element ID to the corresponding node, check its `inputs`, upstream edges, and the variable values flowing into it.
+
+If the local `.flow` file may differ from what was deployed, fetch the deployed BPMN definition:
+
+```bash
+uip maestro flow instance asset <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json
+```
+
+Additional instance inspection commands:
+
+```bash
+uip maestro flow instance element-executions <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json  # per-element execution details
+uip maestro flow instance cursors <INSTANCE_ID> --folder-key <FOLDER_KEY> --output json             # current execution cursor positions
+```
+
+## Step 5 — Traces (last resort)
+
+Traces are verbose but contain the full execution timeline. Use them only when incidents and variables are insufficient:
+
+```bash
+uip maestro flow job traces <JOB_KEY> --output json
+```
+
+> **Always use CLI commands for troubleshooting — never call the underlying APIs directly.**
+
+## CLI command reference
+
+### uip maestro flow instance
+
+Inspect and manage Flow process instances. **Requires `uip login`.** All subcommands require `--folder-key <FOLDER_KEY>` (`-f` shorthand).
+
+```bash
+uip maestro flow instance list --output json                                                        # list all instances
+uip maestro flow instance get <INSTANCE_ID> -f <FOLDER_KEY> --output json                           # get instance details
+uip maestro flow instance incidents <INSTANCE_ID> -f <FOLDER_KEY> --output json                     # get incidents for a failed instance
+uip maestro flow instance variables <INSTANCE_ID> -f <FOLDER_KEY> --output json                     # get runtime variable values
+uip maestro flow instance variables <INSTANCE_ID> -f <FOLDER_KEY> --parent-element-id <ELEMENT_ID> --output json  # scope to a specific element
+uip maestro flow instance element-executions <INSTANCE_ID> -f <FOLDER_KEY> --output json            # get per-element execution details
+uip maestro flow instance asset <INSTANCE_ID> -f <FOLDER_KEY> --output json                         # get the deployed BPMN definition
+uip maestro flow instance cursors <INSTANCE_ID> -f <FOLDER_KEY> --output json                       # get current execution cursor positions
+```
+
+> **Lifecycle commands** (`pause` / `resume` / `cancel` / `retry`) are operate concerns — see the [Operate manage guide](../operate/manage.md).
+
+### uip maestro flow incident
+
+Get incident details for failed flows. **Requires `uip login`.**
+
+```bash
+uip maestro flow incident summary --output json                                    # get incident summaries across all processes
+uip maestro flow incident get <INCIDENT_ID> --folder-key <FOLDER_KEY> --output json # get full details for a specific incident
+```
+
+Use `instance incidents <INSTANCE_ID>` to get incidents scoped to a specific run, then `incident get <INCIDENT_ID>` for full detail on a specific incident.