From 9684592de5e09eb84f782c603a868e1d7a1f3fa9 Mon Sep 17 00:00:00 2001 From: tmatup <51425734+tmatup@users.noreply.github.com> Date: Thu, 7 May 2026 11:23:22 -0700 Subject: [PATCH 1/2] docs(uipath-maestro-flow): refresh validate error quality MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit flow-workbench [#1479](https://github.com/UiPath/flow-workbench/pull/1479) and cli [#1896](https://github.com/UiPath/cli/pull/1896) materially sharpen the diagnostics that `uip maestro flow validate` emits. Two updates so the skill no longer describes the pre-fix behaviour: 1. **`editing-operations-json.md` + `file-format.md`** — `sourceHandle`-vs- `sourcePort` and missing-`targetPort` mistakes were previously called out as producing a "vague root error". Post-fix, the validator returns the precise edge path (`[error] [edges[N].sourcePort] expected string, received undefined`), so the gotchas now describe the real path the agent sees and reinforce that the path identifies the offending edge entry exactly. 2. **`failure-modes.md` — "validate passes, debug faults"** — the "connector input fields with hand-written `inputs.detail` (missing `essentialConfiguration` block)" failure mode was incorrectly listed as a debug-only fault. The IS SDK's `validateConfiguration` rule has always caught the structural cases (empty configuration, missing envelope, invalid JSON) at validate time; cli #1896 also adds shape hints pointing at `uip maestro flow node configure`. Move that family into a new "structural rules **do** catch" section so agents look at the validate output (not `flow debug`) for those titles. No CLI flow / behavior change required of skill consumers — these are documentation-fidelity edits that align the diagnostic phrasings with what the validator actually emits today. --- .../author/references/editing-operations-json.md | 2 +- .../references/diagnose/references/failure-modes.md | 11 +++++++++-- .../references/shared/file-format.md | 4 ++-- 3 files changed, 12 insertions(+), 5 deletions(-) diff --git a/skills/uipath-maestro-flow/references/author/references/editing-operations-json.md b/skills/uipath-maestro-flow/references/author/references/editing-operations-json.md index 65d247ec9..87bd83880 100644 --- a/skills/uipath-maestro-flow/references/author/references/editing-operations-json.md +++ b/skills/uipath-maestro-flow/references/author/references/editing-operations-json.md @@ -30,7 +30,7 @@ Before editing the `.flow` file, ensure each of the following is handled. These 1. **Locate the canonical `.flow` file.** Before any `Edit` / `Write`, find the flow project directory — it is the directory that contains `project.uiproj`. The canonical `.flow` lives **next to** that `project.uiproj`, not at the solution root. Commands like `uip solution new ` + `uip maestro flow init ` create nested paths (`//project.uiproj`); the `.flow` you must edit is `//.flow`, not `/.flow`. Run `find . -name project.uiproj -type f` and pin every `Edit` / `Write` call to the sibling file. `uip maestro flow validate .flow` will accept a misplaced file, so validation alone does **not** confirm the right target — only the colocation with `project.uiproj` does. 2. **Definitions and versions.** For every new node type, run `uip maestro flow registry get --output json`. Copy the returned node definition object **verbatim** into `definitions[]` — one entry per unique `type:typeVersion`. Depending on CLI/plugin version, the node definition may appear as `Data.Node` or as the top-level object containing fields such as `nodeType`, `version`, and `handleConfiguration`; copy that node object, not the surrounding `Result` / `Code` envelope. Then set each node instance's `typeVersion` to the exact copied definition `version` value. The validator matches `type:typeVersion` exactly; `typeVersion: "1.0.0"` does not match a registry definition with `"version": "1.0"`. Never hand-write or paraphrase definitions (see "Every node type needs a `definitions` entry" in [the Author capability index](../CAPABILITY.md)). 3. **Unique node ID.** Pick a camelCase ID that does not collide with existing node IDs. Prefer meaningful names (`fetchUsers`, `filterActive`) since they become part of every `$vars..*` expression. -4. **`sourcePort` and `targetPort` on every edge.** Omitting `targetPort` is the #1 validation error (see "`targetPort` is required on every edge" in [the Author capability index](../CAPABILITY.md)). Use `sourcePort`, never `sourceHandle`; `sourceHandle` is not part of the `.flow` edge schema and produces the vague root error `Invalid input: expected string, received undefined`. Look up ports in the relevant plugin's `planning.md` or in [file-format.md — Standard ports](../../shared/file-format.md). +4. **`sourcePort` and `targetPort` on every edge.** Omitting `targetPort` is the #1 validation error (see "`targetPort` is required on every edge" in [the Author capability index](../CAPABILITY.md)). Use `sourcePort`, never `sourceHandle`; `sourceHandle` is not part of the `.flow` edge schema and produces a precise schema error such as `[error] [edges[N].sourcePort] Invalid input: expected string, received undefined` (the path tells you exactly which edge entry is missing the `sourcePort` key). Look up ports in the relevant plugin's `planning.md` or in [file-format.md — Standard ports](../../shared/file-format.md). 5. **Node outputs block.** Every data-producing node needs an `outputs` block on the node instance (not just in `definitions`). Action nodes: `output` + `error`. Trigger nodes: `output`. End/terminate: none. (See "Every node that produces data MUST have `outputs` on the node instance" in [the Author capability index](../CAPABILITY.md).) 6. **`variables.nodes[]`.** Add entries for the new node's outputs. Optional under today's runtime, but expected for completeness and diff clarity. 7. **On delete — cascade manually.** Remove the node from `nodes`. Then sweep `edges[]` for any with matching `sourceNodeId`/`targetNodeId`. Then prune `definitions[]` if this was the last user of the type. Then check `bindings_v2.json` — but only remove a connector binding if no remaining node uses the same connector (bindings are shared at the connector level). diff --git a/skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md b/skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md index c6e1033f7..e62807054 100644 --- a/skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md +++ b/skills/uipath-maestro-flow/references/diagnose/references/failure-modes.md @@ -206,15 +206,22 @@ Local `uip maestro flow validate` returns `Result: Success`. The same flow fails ### Cause -Multiple. `flow validate` is a JSON schema + cross-reference check; it does not catch: +Multiple. `flow validate` is a JSON schema + cross-reference check plus a small set of structural rules; it does not catch: - Missing `=js:` prefix → see [MST-9107](#mst-9107--js-prefix-missing) - 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) -- Connector input fields with hand-written `inputs.detail` (missing `essentialConfiguration` block) — re-run `uip maestro flow node configure` to populate properly - HITL `completed` port unwired → see [HITL `completed` port unwired](#hitl-completed-port-unwired) - Stale `layout` data → see [MST-9061](#mst-9061--misshapen-rectangle-nodes-in-studio-web) (cosmetic, not faulting) +The structural rules **do** catch (validate exits non-zero, with a shape hint pointing at `uip maestro flow node configure` as the canonical authoring path): + +- Connector `inputs.detail.configuration` missing or empty +- Connector `inputs.detail.configuration` decoded but lacking the `essentialConfiguration` envelope +- Connector `inputs.detail.configuration` containing invalid JSON inside the `=jsonString:` prefix + +If you see one of those error titles, re-run `uip maestro flow node configure` rather than hand-editing. + ### 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. diff --git a/skills/uipath-maestro-flow/references/shared/file-format.md b/skills/uipath-maestro-flow/references/shared/file-format.md index e151c9e81..fe39c3a44 100644 --- a/skills/uipath-maestro-flow/references/shared/file-format.md +++ b/skills/uipath-maestro-flow/references/shared/file-format.md @@ -202,9 +202,9 @@ Each key in `layout.nodes` is a node `id`. `flow tidy` creates an entry for ever } ``` -> **Gotcha**: `targetPort` is required. Omitting it produces `[error] [edges.N.targetPort] expected string, received undefined` at validate time. +> **Gotcha**: `targetPort` is required. Omitting it produces `[error] [edges[N].targetPort] expected string, received undefined` at validate time. > -> **Gotcha**: the source field is `sourcePort`, not `sourceHandle`. If you write `sourceHandle`, validation fails with the vague root-level error `Invalid input: expected string, received undefined`. +> **Gotcha**: the source field is `sourcePort`, not `sourceHandle`. If you write `sourceHandle`, validation fails with `[error] [edges[N].sourcePort] expected string, received undefined` — the path identifies the offending edge entry exactly. ## Definition entry From cde8f5f71253bde98598e8c9cee6013d8d950acd Mon Sep 17 00:00:00 2001 From: tmatup <51425734+tmatup@users.noreply.github.com> Date: Thu, 7 May 2026 11:48:09 -0700 Subject: [PATCH 2/2] docs(uipath-maestro-flow): harmonize Zod error prefix in file-format gotchas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address github-actions[bot] PR #640 review (Severity: Low) — the two edge-port gotchas in file-format.md quoted the Zod error as bare `expected string, received undefined`, while editing-operations-json.md and the actual runtime output carry the `Invalid input:` prefix that Zod 4 emits. Harmonize the wording so agents pattern-match the same string across both files. Pre-existing inconsistency (predates this PR's earlier commits) but a trivial edit to land alongside. --- skills/uipath-maestro-flow/references/shared/file-format.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/uipath-maestro-flow/references/shared/file-format.md b/skills/uipath-maestro-flow/references/shared/file-format.md index fe39c3a44..5b68e5ddf 100644 --- a/skills/uipath-maestro-flow/references/shared/file-format.md +++ b/skills/uipath-maestro-flow/references/shared/file-format.md @@ -202,9 +202,9 @@ Each key in `layout.nodes` is a node `id`. `flow tidy` creates an entry for ever } ``` -> **Gotcha**: `targetPort` is required. Omitting it produces `[error] [edges[N].targetPort] expected string, received undefined` at validate time. +> **Gotcha**: `targetPort` is required. Omitting it produces `[error] [edges[N].targetPort] Invalid input: expected string, received undefined` at validate time. > -> **Gotcha**: the source field is `sourcePort`, not `sourceHandle`. If you write `sourceHandle`, validation fails with `[error] [edges[N].sourcePort] expected string, received undefined` — the path identifies the offending edge entry exactly. +> **Gotcha**: the source field is `sourcePort`, not `sourceHandle`. If you write `sourceHandle`, validation fails with `[error] [edges[N].sourcePort] Invalid input: expected string, received undefined` — the path identifies the offending edge entry exactly. ## Definition entry