@uipath/skills 1.195.0 → 1.196.0

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/read-range-sheet-not-found.md

@@ -0,0 +1,146 @@
+---
+confidence: medium
+---
+
+# Read Range — Sheet With The Specified Name Does Not Exist
+
+## Context
+
+A `UiPath.Excel.Activities` Read Range (or any range-addressed Excel activity) opens the workbook successfully but fails when it tries to resolve the configured `SheetName` against the workbook's actual sheet titles. No sheet in the workbook matches the configured name exactly, so the activity throws before any range parsing or cell reads happen.
+
+What this looks like:
+- Activity fails with `UiPath.Excel.BusinessException: The sheet with the name '<configured-name>' does not exist.` (legacy `Excel Application Scope` family) or `UiPath.Excel.ExcelException: Sheet '<configured-name>' does not exist in the workbook.` (modern `Use Excel File` family). Exact wording shifts across package versions; the constant signal is the literal configured `SheetName` echoed back in the error.
+- The configured workbook path is correct — the file opened (no preceding `IOException`, `FileNotFoundException`, or password-protection error).
+- The error names a `SheetName` that the user believes exists. Comparing against the workbook's actual sheets is the next step.
+- Affects every range-addressed Excel activity: `Read Range`, `Read Cell`, `Read Column`, `Read Row`, `Write Range`, `Write Cell`, `Append Range`, `Filter Range`, `Pivot Range`, `Sort Range`, `For Each Row in Excel`, etc.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Typo in the configured sheet name** — `SheetName` literal differs from the actual sheet by one or more characters. Most common when the value is hard-coded in the workflow and the workbook is authored by a different person. Symptom: error names a sheet that simply isn't in the workbook's sheet list.
+2. **Case mismatch under the OpenXML provider** — `Use Excel File` running on the OpenXML provider (Excel not installed or COM fallback not triggered) treats sheet names **case-sensitively**. Excel COM (legacy `Excel Application Scope`, or `Use Excel File` falling back to COM) is case-insensitive. Symptom: same workflow that worked on a Studio dev box (where Excel is installed → COM) fails on a headless Robot host (no Excel → OpenXML). The configured name differs from the actual sheet only by letter casing.
+3. **Sheet was renamed upstream** — the workbook publisher renamed the sheet (`Sheet1` → `January 2026`, `Data` → `Raw Data`, etc.). The workflow's configured name is now stale. Symptom: error names the OLD sheet; opening the workbook in Excel shows the NEW sheet name.
+4. **Sheet was deleted upstream** — the workbook publisher removed the sheet entirely. Symptom: error names a sheet that no longer exists; the data the workflow is meant to read may have been moved to a different sheet.
+5. **Leading or trailing whitespace** — the configured `SheetName` is `"Data "` (trailing space) or `" Data"` (leading space) and the actual sheet is `"Data"` (or vice versa). Common when the name comes from a variable concatenated with another string (`"Data " + month`) or from an external source (queue item, asset, CSV) where whitespace is not trimmed. Symptom: error wording shows the whitespace if you copy it byte-exact; visually the configured name looks correct.
+6. **Non-ASCII or look-alike characters** — sheet name contains characters that look identical but are different code points: regular space (`U+0020`) vs. non-breaking space (`U+00A0`), Latin `a` (`U+0061`) vs. Cyrillic `а` (`U+0430`), straight quote vs. curly quote. Common when the name was copy-pasted from email, Word, or an internationalized data source. Symptom: configured name and actual name look identical in the UI but bytes differ.
+7. **Variable resolved to wrong value at runtime** — the `SheetName` property is a dynamic expression (`row("Region").ToString()`, `Environment.GetEnvironmentVariable(...)`, etc.) that resolved to an unexpected value at runtime. Symptom: error names a sheet that nobody configured deliberately — possibly `Null`, an empty string `""`, a row index like `0`, or an unrelated cell value.
+8. **Sheet is hidden or very-hidden** — the configured sheet name DOES exist in the workbook but is set to `xlSheetHidden` or `xlSheetVeryHidden` visibility. The OpenXML provider returns hidden sheets in lookups, but historical bug reports show legacy `Excel Application Scope` skipping very-hidden sheets when resolving by name on some `UiPath.Excel.Activities` versions. Symptom: an interactive admin can see the sheet via Excel's `Format → Sheet → Unhide`, but the activity reports it missing; `Get Workbook Sheets` may or may not list it depending on provider and version.
+
+What to look for:
+- **The literal configured `SheetName` echoed in the error** — the authoritative input at runtime. Don't trust the design-time expression alone; the runtime value may differ.
+- **The workbook's actual sheet titles** — open the workbook in Excel, or enumerate via a one-off `Get Workbook Sheets` activity in a scratch project. Compare verbatim against the configured name.
+- **Provider in use** — COM or OpenXML. Determines whether case-sensitivity applies. Legacy `Excel Application Scope` is always COM. Modern `Use Excel File`: OpenXML by default; falls back to COM when `Read Formatting`, `Edit Password`, or macro-related properties are set.
+- **Whether the workbook was recently re-authored** — ask whether the upstream owner renamed, deleted, or restructured sheets. A `git log` / SharePoint version history check on the workbook itself is conclusive.
+- **Whether `SheetName` is a literal or a dynamic expression** — workflow source. Dynamic expressions point at branch 7.
+- **Byte-level comparison if the names look identical** — for branches 5 and 6. Paste both into a hex viewer or use `[char]<n>` in PowerShell to inspect code points.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Confirm the activity, configured `SheetName`, and workbook.** From workflow source: which activity (`Read Range` / `Read Cell` / etc.), which scope (`Excel Application Scope` vs. `Use Excel File`), and the configured `SheetName` expression — literal string or dynamic. From `uip or jobs get <job-key> --output json` → `Info`: the exception class, the workbook path, and the `<configured-name>` echoed in the error string.
+
+2. **Distinguish branch 7 (variable resolved wrong) immediately.** If the `SheetName` expression in source is dynamic, the runtime value is what matters. If the error names something nonsensical (`Null`, empty string, `0`, an integer, a row value, a path fragment), the variable resolved to the wrong thing — go to step 7. If the error names a plausible sheet (`Sheet1`, `Data`, `January 2026`), continue with branches 1-6.
+
+3. **Enumerate the workbook's actual sheets.** If the user can open the workbook in Excel, list the sheet titles verbatim. If they cannot (headless host, file lives on a share they don't access), have them run a one-off scratch workflow with `Get Workbook Sheets` against the same path on the same host. The returned `IEnumerable<String>` is the authoritative list.
+
+4. **Compare verbatim against the configured name.**
+   - **Identical match in the list** → not this playbook. The activity should not have failed; check the next-most-likely playbook (file-locked, file-not-found) or look for a version-specific package bug.
+   - **No similar name in the list** → branch 4 (deleted) or branch 1 (typo big enough that no close match exists).
+   - **A close-but-different name in the list** → continue with branches 1, 2, 3, 5, or 6 per the diff:
+     - Exactly one character different → branch 1 (typo).
+     - Same letters, different casing → branch 2 (case mismatch).
+     - Different word entirely, recent rename → branch 3.
+     - Same visible characters but one has leading/trailing space → branch 5 (whitespace).
+     - Same visible characters, no obvious diff → branch 6 (look-alike characters). Continue to step 5.
+
+5. **Detect whitespace / look-alike characters when the names look identical.**
+   ```powershell
+   $configured = '<configured-name>'
+   $actual = '<actual-name-from-workbook>'
+   "configured: $($configured.Length) chars  bytes: $(([System.Text.Encoding]::UTF8.GetBytes($configured) | ForEach-Object { $_.ToString('X2') }) -join ' ')"
+   "actual:     $($actual.Length) chars  bytes: $(([System.Text.Encoding]::UTF8.GetBytes($actual) | ForEach-Object { $_.ToString('X2') }) -join ' ')"
+   ```
+   - Length differs → branch 5 (whitespace at one end).
+   - Length equal, byte sequences differ → branch 6 (look-alike character at some position).
+   - Length equal, byte sequences equal → not a name-mismatch issue; recheck step 4.
+
+6. **Determine the provider in use (branch 2 confirmation).** Legacy `Excel Application Scope` is always COM (case-insensitive sheet lookups) — branch 2 is impossible here. Modern `Use Excel File`:
+   - If the activity inputs include `Read Formatting: True`, `Edit Password`, or macro-related properties → COM fallback, case-insensitive.
+   - If none of those are set → OpenXML, case-sensitive on the OpenXML version in use.
+   - Verify by re-running on a host where Excel **is** installed; if the same workflow succeeds there with the same workbook, branch 2 is confirmed.
+
+7. **Trace the dynamic `SheetName` expression (branch 7).** If the configured name is a variable / expression:
+   - Add a `LogMessage` immediately before the failing activity that logs `String.Format("[SheetName resolved to: '{0}']", <expression>)`. Re-run and observe the runtime value.
+   - Or inspect `jobs logs` if the workflow already logs the value.
+   - Trace the upstream variable assignments to find where the bad value was produced (null-safe lookup, queue item field missing, asset typo, etc.).
+
+The root cause is **which specific kind of mismatch** between the configured `SheetName` and the workbook's actual sheet titles — not "the sheet doesn't exist" generically. A confirmed finding names the configured name verbatim, the actual sheet name(s), and one of the cause-branches.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Typo:**
+  - Update the `SheetName` property on the activity to match the actual sheet name verbatim. If the value is a literal in the workflow, edit it directly. If it comes from a config asset or argument, fix the source.
+  - Prevention: enumerate sheets via `Get Workbook Sheets` at job start when the workbook is authored externally and the sheet name is not stable. Validate the configured name against the list before reading; fail fast with a clear message if not present.
+
+- **Branch 2 — Case mismatch on OpenXML:**
+  - **Match casing in the workflow** — change the configured `SheetName` to the exact casing the workbook uses. This is the cheapest fix and avoids depending on provider behavior.
+  - **Or force the COM provider** — set `Read Formatting: True` (or another COM-forcing property) on the `Use Excel File` scope so the activity uses Excel COM, which is case-insensitive. Requires Excel installed on the host.
+  - **Or normalize at read time** — if the casing is unstable across workbook versions, enumerate sheets via `Get Workbook Sheets` and look up the actual case via `sheets.First(Function(s) s.Equals(target, StringComparison.OrdinalIgnoreCase))`.
+  - Prevention: do not assume case-insensitive sheet lookups on `Use Excel File`. Default to case-sensitive matching; document the convention.
+
+- **Branch 3 — Sheet was renamed upstream:**
+  - Update the configured `SheetName` to the new name.
+  - Coordinate with the workbook publisher: agree on a stable sheet name convention, or use a sentinel header row / named range that the workflow can locate independent of sheet title.
+  - Prevention: do not hard-code sheet names that the workbook publisher may rename. If the workbook layout is owned by a different team, encode the layout contract somewhere stable (sheet name AND header-row signature; named ranges; a metadata sheet).
+
+- **Branch 4 — Sheet was deleted upstream:**
+  - Confirm where the deleted sheet's data went (moved to another sheet? rolled up? archived elsewhere?). Update the workflow to read from the new location.
+  - If the deletion was unintentional, restore from version history (SharePoint / OneDrive: Version History → Restore; local file: Excel's `File → Info → Version History`).
+  - Prevention: treat the workbook layout as a contract. Don't delete sheets without coordinating with downstream consumers.
+
+- **Branch 5 — Leading or trailing whitespace:**
+  - **If the workbook's sheet name has the whitespace** (the publisher named it `"Data "`): either ask the publisher to rename without whitespace (cleanest), or update the workflow's configured name to include the whitespace verbatim.
+  - **If the workflow's configured name has the whitespace** (it came from a variable or concatenation): trim. `SheetName = sheetVar.Trim()`. Audit the upstream source.
+  - Prevention: always `.Trim()` external-sourced sheet names. Reject names with whitespace at the boundaries at validation time.
+
+- **Branch 6 — Non-ASCII / look-alike characters:**
+  - Identify the offending code point from the byte comparison in investigation step 5. Replace it with the intended character in whichever side has the wrong code point (usually the workflow's configured name).
+  - Prevention: when sheet names come from external sources (especially emails, Word docs, internationalized data), normalize: `System.Text.RegularExpressions.Regex.Replace(name, " ", " ")` for NBSP, or stronger Unicode normalization (`String.Normalize(NormalizationForm.FormC)`) for combining characters.
+
+- **Branch 7 — Variable resolved to wrong value:**
+  - Fix the upstream source of the variable. Common patterns:
+    - Null-safe queue item field access (`If(item.SpecificContent.ContainsKey("Sheet"), item.SpecificContent("Sheet").ToString(), defaultSheet)`).
+    - Asset / config lookup that returned empty — make the asset required and validate at job start.
+    - String concatenation that included an unexpected value (`"Data " + month` where `month` was `Nothing`).
+  - Add a guard before the activity that fails the workflow with a clear message when the resolved name is empty, null, or doesn't match a known sheet — rather than letting the BusinessException surface generically.
+  - Prevention: validate dynamic sheet names against `Get Workbook Sheets` output at the start of the job. Treat an unresolved sheet name as a configuration error, not a runtime error.
+
+- **Branch 8 — Hidden or very-hidden sheet:**
+  - Unhide the sheet in Excel: `Format → Sheet → Unhide` (for `xlSheetHidden`), or open the VBA editor (`Alt+F11`) and set the sheet's `Visible` property to `xlSheetVisible` (for `xlSheetVeryHidden` — Excel's `Unhide` dialog does not list very-hidden sheets).
+  - If the sheet must remain hidden (presentation reasons), update the workflow to enumerate sheets via a method that includes hidden ones, and confirm the configured name still matches verbatim.
+  - Upgrade `UiPath.Excel.Activities` to the latest version if the project is on an older release; historical bug reports show legacy `Excel Application Scope` skipping very-hidden sheets in some versions.
+  - Prevention: do not very-hide data sheets that workflows depend on. Either keep them visible, OR document the dependency in the workbook itself (cover sheet / metadata sheet listing all programmatically-read sheets).
+
+## Anti-patterns (what NOT to do)
+
+Two common pieces of advice for this failure mode are anti-patterns that hide the bug without fixing it. The agent should NOT recommend either as a primary resolution.
+
+- **Switching from `Use Excel File` to `Excel Application Scope` (or vice versa) as a "magic fix".** Provider divergence between OpenXML and Excel COM is the cause of branch 2 (case mismatch) — switching scopes coincidentally hides that one branch by replacing case-sensitive lookup with case-insensitive lookup. It does NOT fix branches 1, 3, 4, 5, 6, 7, or 8, and it ties the workflow to a host that must have Excel installed (Excel Application Scope is COM-only). The real fix for branch 2 is to match the casing in the workflow, or to force COM explicitly via a documented property. Treat "try the other scope" as a debugging step (does the same workflow succeed under COM?), not as the resolution.
+
+- **Wrapping the activity in a Try Catch to "handle missing tabs gracefully" with no real recovery path.** A bare `Catch System.Exception` (or `UiPath.Excel.BusinessException`) that only logs and continues turns the workflow into a silent-failure pipeline: the DataTable is empty, downstream activities produce zeros / empty reports / no queue items, and the operator sees a job that completed Successfully despite reading nothing. Use Try Catch only as part of a real recovery path: fall back to a different sheet, send a notification, mark a queue item Failed, or re-throw a domain-specific exception. The same anti-pattern is called out as an orphan-cause in [`read-range-file-locked.md`](./read-range-file-locked.md) — silent exception suppression around Excel scopes is consistently harmful, not helpful.
+
+## Prevention (cross-branch)
+
+- Enumerate sheets at job start (`Get Workbook Sheets`) and validate every configured sheet name against the actual list. Fail fast with a message that includes the configured name AND the actual list — saves operators 20 minutes of guessing.
+- Treat the workbook layout as a contract between publisher and consumer. Sheet renames are a breaking change; coordinate them.
+- Default to case-sensitive matching in your workflows even when the provider is currently case-insensitive — you may switch to a headless OpenXML-only host later.
+- `.Trim()` any sheet name that comes from outside the workflow's literal source code.
+- Normalize Unicode for names sourced from email / Word / internationalized data.
+- Log the resolved sheet name at the start of any Excel scope when the name is dynamic; future debugging gets significantly cheaper.
+
+## Related
+
+- Other Excel Read Range failure fingerprints (file-locked, file-not-found, null-reference on formatted files) are separate playbooks — see [`../summary.md`](../summary.md).
+- For shared / cloud Excel workbooks accessed via Microsoft Graph rather than the local filesystem, see [`o365-activities/overview.md`](../../o365-activities/overview.md).

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/write-cell-failures.md

@@ -0,0 +1,131 @@
+---
+confidence: medium
+---
+
+# Write Cell Failures
+
+## Context
+
+A `UiPath.Excel.Activities` `Write Cell` activity (Classic Workbook surface, Classic `Excel Application Scope`, or Modern `Use Excel File`) writes a single value or formula to a target cell. Failures originate in one of four places: the file (locked by another process / wrong scope owns it), the cell target (sheet name mismatch, bad cell reference, protected target), the value (formula syntax rejected by Excel's parser), or the surrounding loop pattern (repeated Write Cell calls thrashing Excel's COM state).
+
+What this looks like — Write Cell faults surface as one of these signatures:
+
+- `System.IO.IOException: The process cannot access the file '<path>' because it is being used by another process.` — file lock, branch 1.
+- `UiPath.Excel.BusinessException: The data you want to write has a wrong format, or Excel is busy.` — formula syntax (branch 2) or Excel state thrash (branch 3); same wording for two different causes, distinguish by context.
+- `UiPath.Excel.BusinessException: The sheet with the name '<name>' does not exist.` — branch 4, identical signature to Read Range's sheet-not-found.
+- `System.Runtime.InteropServices.COMException` with message about a protected sheet or read-only workbook — branch 5.
+- `UiPath.Excel.BusinessException: The cell reference '<ref>' is invalid.` or `Application-defined or object-defined error` from Excel COM — branch 6, bad A1 notation / unknown named range.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Workbook locked OR Classic/Modern scope conflict** — A different process holds the file's lock, OR a Classic `Write Cell` (the standalone "Workbook" surface) targets a workbook that a surrounding `Excel Application Scope` / `Use Excel File` has already opened. The Classic Workbook surface accesses the file's raw bytes directly and refuses to write while any other process — including UiPath's own Excel COM scope — holds it. The error wording is the same `System.IO.IOException` as Read Range branch 1; the divergent fix is "stop mixing scopes" rather than "kill the locker."
+2. **Formula syntax rejected** — The configured `Value` is a formula string (`=SUM(A1:A10)`, `=IF(...)`) that Excel's formula parser refuses. Three common causes: parameter separators (UiPath requires `,` even when the host's Windows regional setting expects `;`), unescaped or unbalanced quotes (string literals inside formulas need `""` around inner quotes when assembled from a UiPath VB.NET expression), or function names that depend on an add-in not loaded on the Robot's Excel session.
+3. **Loop-induced "Excel is busy" / memory thrash** — `Write Cell` is called inside a `For Each Row` (or any tight loop) so the activity opens, writes, saves, and closes the workbook on every iteration. After ~100–500 iterations Excel COM accumulates COM-object leaks, the file lock churn races with itself, and the activity fails with the same "wrong format, or Excel is busy" wording as branch 2 — but here the wording is misleading: nothing's wrong with the data, the Excel instance is destabilized. Symptom: first N iterations succeed, then a sudden failure mid-loop; restarting the job gets through a different N iterations before failing again.
+4. **Sheet name mismatch** — Configured `SheetName` does not match any sheet in the workbook. Verbatim the same diagnostic as the Read Range version — typos, OpenXML case-sensitivity, sheet renamed upstream, leading/trailing whitespace, look-alike Unicode characters, or a dynamic variable that resolved to the wrong value. See [`read-range-sheet-not-found.md`](./read-range-sheet-not-found.md) for the full investigation chain; the same diagnostic applies on the write side.
+5. **Protected sheet or workbook** — The sheet has `Protect Sheet` enabled (with or without a password) or the workbook is opened read-only (file system ACL denies write, `Mark as Final` flag is on, the file came from email with `Protected View`, or the activity is running under a Modern `Use Excel File` scope with `Read-only mode: True`). Excel rejects the write with a COMException mentioning protection, or the activity returns silently with no observable change to the file.
+6. **Invalid cell reference** — Configured `Cell` is malformed A1 notation (`AA0`, `B`, `1B`, leading whitespace), out of the workbook's bounds (`A1048577` exceeds the 1,048,576-row limit on `.xlsx`), or a named range that does not exist in the workbook's defined names. Same diagnostic as branch 4 (sheet mismatch) but at one level deeper: the sheet resolved, the cell reference inside it did not.
+
+What to look for:
+
+- **The exception class and message** — first signal. `IOException` → branch 1. "`wrong format, or Excel is busy`" → branch 2 or 3 (distinguish by loop context). "`sheet with the name`" → branch 4. COMException with "`protected`" / "`read-only`" → branch 5. "`cell reference`" / "`Application-defined or object-defined`" → branch 6.
+- **Workflow source** — which `Write Cell` surface? Classic Workbook (no enclosing scope), Classic inside `Excel Application Scope`, or Modern `Write Cell` inside `Use Excel File`. The surface determines whether branch 1's scope-conflict variant applies.
+- **The configured `Value`** — literal string vs. formula (`=…`). Branch 2 is only possible when the value is a formula.
+- **Loop context** — is `Write Cell` inside `For Each` / `For Each Row` / `While`? Branch 3 is impossible outside a loop.
+- **The configured `Cell`** — literal A1 notation, an expression, or a named range. Bad expressions are branch 6.
+- **The workbook's protection state** — open the file in Excel; `Review → Protect Sheet` shows protection status; `File → Info` shows `Mark as Final` and `Protected View`. Branch 5 confirmation.
+- **Job logs around the failure** — the activity's Trace logs echo the configured `Value` (truncated) and the resolved `Cell` / `SheetName`. Mismatches between source and resolved values point at branch 4 / 6 with a dynamic-expression cause.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, activity, and target.** From `uip or jobs get <job-key> --output json` → `Info`: exception class and full message. From workflow source: the `Write Cell` surface (Classic Workbook / Classic inside scope / Modern), configured `SheetName`, `Cell`, and `Value` (literal or expression). Look at job logs (`uip or jobs logs <key>`) for the activity's Trace lines, which echo the resolved runtime values.
+
+2. **Branch the diagnostic on the exception signature.**
+   - `System.IO.IOException` → branch 1; go to step 3.
+   - `BusinessException: ... sheet with the name '<x>' does not exist` → branch 4; see [`read-range-sheet-not-found.md`](./read-range-sheet-not-found.md). Done.
+   - `BusinessException: ... wrong format, or Excel is busy` → branches 2 or 3; go to step 4.
+   - `COMException` with "protected" / "read-only" / `0x800A03EC` near `Worksheet.Protect` → branch 5; go to step 5.
+   - `BusinessException: ... cell reference '<x>' is invalid` or `Application-defined or object-defined error` → branch 6; go to step 6.
+
+3. **Distinguish branch 1's two variants (lock vs. scope conflict).** If the activity is **Classic Workbook `Write Cell`** (no surrounding scope) and the workflow ALSO has an `Excel Application Scope` or `Use Excel File` for the same path elsewhere in the call graph, the scope-conflict variant applies — the Modern/Classic scope still holds the file when the Classic Workbook activity tries to write. Fix is structural (don't mix), not host-side (no killing required). If the Write Cell is the only Excel reference to that path, the issue is an external locker — pivot to [`read-range-file-locked.md`](./read-range-file-locked.md) for the full lock-investigation chain (orphan EXCEL.EXE, user editing, network share, AV scanner, concurrent jobs).
+
+4. **Distinguish branch 2 from branch 3 (formula syntax vs. loop thrash).** Both surface with the "wrong format, or Excel is busy" wording.
+   - If the activity is inside a `For Each` / `For Each Row` / `While` loop AND fails partway through (some iterations succeeded before the failure) → branch 3 (loop thrash). The misleading "wrong format" wording masks Excel COM instability. Confirm: `uip or jobs logs <key>` shows successful iterations preceding the fault.
+   - If the activity is not in a loop, OR fails on the first iteration of a loop → branch 2 (formula syntax). Examine the configured `Value`. Formula? Inspect for:
+     - Parameter separators: `=SUM(A1;A10)` is invalid; must be `=SUM(A1,A10)` regardless of host's Windows regional setting.
+     - Quote escaping: in UiPath VB.NET, an inner string literal inside a formula expression needs doubled quotes. Source: `"=IF(A1=""x"",1,0)"` produces the formula `=IF(A1="x",1,0)` at runtime. Single quotes at the boundaries or unbalanced doubled quotes produce malformed formulas.
+     - Function names: `=IFERROR(...)` and similar exist in modern Excel COM but not the OpenXML provider; functions from add-ins (e.g., `=BAHTTEXT(...)` from the Thai add-in) require the add-in registered for the Robot user.
+   - If the value is not a formula and the activity is not in a loop → uncommon edge case; check for invisible characters in the `Value` itself (NBSP, BOM, control chars) before assuming Excel COM bug.
+
+5. **Confirm branch 5 (protected sheet / workbook).** Open the workbook in Excel on the Robot user's profile (or have the user do so):
+   - `Review → Protect Sheet` — if "Unprotect Sheet" is shown, the sheet is protected. The target cell may or may not be in the protected-cells range; check `Format Cells → Protection → Locked`.
+   - `File → Info` — "Always Open Read-Only" or "Mark as Final" badges indicate workbook-level write blocks.
+   - File system: `Get-Acl '<path>' | Format-List` confirms the Robot user has write permission. NTFS read-only or share-level read-only blocks the write at the OS layer.
+   - If the workbook came from email or download: Excel's `Protected View` blocks writes until "Enable Editing" is clicked — a Robot session never clicks it.
+
+6. **Confirm branch 6 (invalid cell reference).** Compare the configured `Cell` against:
+   - A1 notation rules: column letters then row number, no whitespace, row ≥ 1, column within the workbook's column count (16,384 for `.xlsx`).
+   - Workbook's defined names: open in Excel → `Formulas → Name Manager`, OR via PowerShell with `OpenXML SDK` if the host has it. The configured cell may be a named range that was renamed / deleted upstream.
+   - Sheet-relative vs. workbook-relative: `Sheet1!A1` syntax is allowed in some surfaces but rejected in others; check whether the activity expects `Cell` to include the sheet prefix or whether the sheet comes from a separate property.
+
+The root cause is **which of the six fault surfaces** (lock, scope conflict, formula syntax, loop thrash, protection, cell reference, sheet mismatch) the failure maps to. A confirmed finding names the surface (Classic Workbook / Classic scope / Modern scope), the resolved runtime values for `SheetName` / `Cell` / `Value`, and one of the cause-branches.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Workbook locked OR Classic/Modern scope conflict:**
+  - **Scope-conflict variant**: replace the standalone Classic Workbook `Write Cell` with one nested inside the surrounding scope. If the scope is Modern (`Use Excel File`), use Modern `Write Cell`. If the scope is Classic `Excel Application Scope`, use Classic `Write Cell` nested inside it. Do not mix Modern scopes with Classic Workbook activities — they own the file by different mechanisms.
+  - **External locker variant**: the file is held by something outside the workflow. Follow [`read-range-file-locked.md`](./read-range-file-locked.md)'s investigation and resolution chain — orphan EXCEL.EXE kill, user-coordinated close, network-share unlock, AV exclusion, etc.
+  - Stop-gap (any variant): add a `Kill Process` activity targeting `EXCEL` immediately before the failing `Write Cell` to terminate stragglers. Treat this as a diagnostic patch, not a permanent fix — it masks scope-cleanup bugs in the workflow.
+
+- **Branch 2 — Formula syntax rejected:**
+  - Replace semicolons with commas in parameter lists. UiPath passes the formula string to Excel verbatim and Excel COM requires commas regardless of the host's regional setting (the Excel UI displays semicolons in non-US locales, but the COM API does not).
+  - Double-quote inner strings: `"=IF(A1=""hello"","""",A1)"` produces `=IF(A1="hello","",A1)`. Verify by logging the resolved formula (`Log Message Level=Info Message=$"Formula: {value}"`) before the Write Cell.
+  - Confirm function availability: `=IFERROR` and other modern functions require Excel 2007+. Functions from add-ins (`=BAHTTEXT`, `=GETPIVOTDATA` against an unloaded PivotCache) need the add-in registered under the Robot user. Replace with primitive equivalents where possible.
+  - For literal values (not formulas) that get misinterpreted as formulas — values starting with `=`, `+`, or `-` — prepend an apostrophe (`'`) or use the activity's `Preserve Format` property to force literal interpretation.
+
+- **Branch 3 — Loop-induced "Excel is busy":**
+  - Replace the cell-by-cell write pattern with bulk Write Range. Read the workbook into a `DataTable` once via `Read Range`, modify rows in memory inside the loop (`row("Column") = newValue`), then `Write Range` the modified table back to the workbook once after the loop. This collapses N file open/close cycles into 2.
+  - If a per-cell pattern is unavoidable (e.g., the writes are interleaved with reads that depend on intermediate computed values), batch them: collect the writes into a `List<(string Cell, object Value)>` during the loop, then drain the list with a single Write Range or repeated Write Cell calls outside the loop where COM thrash is bounded.
+  - Avoid `Save Workbook` inside the loop. Modern `Use Excel File` controls save semantics through the scope's `Auto Save` property; setting it to False and saving once at the end of the workflow eliminates per-iteration disk I/O.
+
+- **Branch 4 — Sheet name mismatch:**
+  - Apply the resolution from [`read-range-sheet-not-found.md`](./read-range-sheet-not-found.md). The write-side fix is identical to the read-side: correct the configured `SheetName`, match casing if on OpenXML, trim whitespace, normalize Unicode, or validate dynamic expressions against `Get Workbook Sheets` output at job start.
+
+- **Branch 5 — Protected sheet or workbook:**
+  - **Sheet protection**: unprotect via `Worksheet.Unprotect` before the write and re-protect after, OR remove protection from the sheet at the workbook source and replace it with per-cell `Locked: False` on the cells the workflow targets. Per-cell unlocking + sheet-wide protection is the safer pattern for production workbooks that humans also edit.
+  - **Workbook read-only / Mark as Final**: open the workbook, remove the `Mark as Final` flag (`File → Info → Mark as Final`), or change file-system ACL to grant the Robot user write access. If the workbook arrived via Protected View (downloaded / emailed), have the publisher trust the source path or unblock the file (`Unblock-File '<path>'` on the Robot host).
+  - **Modern scope with `Read-only mode: True`**: change the scope property to `False`. The default-True is a footgun on `Use Excel File` for workflows that include any Write activity.
+
+- **Branch 6 — Invalid cell reference:**
+  - Fix the A1 notation. Common typos: `B` instead of `B1`, `1B` instead of `B1`, trailing whitespace.
+  - For named ranges: open the workbook in Excel → `Formulas → Name Manager` to confirm the name exists and points where expected. If the name was renamed upstream, update the activity. If the name is dynamic per-workbook, enumerate defined names at job start and validate.
+  - For dynamic `Cell` expressions: log the resolved runtime value (`Log Message Level=Info Message=$"Cell: {cellExpr}"`) before the activity. Validate against the workbook's actual bounds (16,384 cols × 1,048,576 rows for `.xlsx`; `.xls` is smaller).
+
+## Anti-patterns (what NOT to do)
+
+Common quick-fixes for `Write Cell` failures hide the bug without fixing it. The agent should NOT recommend these as primary resolutions.
+
+- **"Add a `Kill Process` activity for EXCEL before every Write Cell."** A blanket `Kill Process` masks scope-management bugs (branch 1 scope-conflict variant), terminates other legitimate Excel work on the host, and creates a brittle workflow that depends on the absence of Excel processes rather than correct scope ownership. Use `Kill Process` as a one-off diagnostic step to confirm a fix candidate, not as a recurring activity. The real fix for branch 1 is to align Modern/Classic scopes correctly; for branch 2/3 it's the formula or the loop pattern.
+
+- **"Wrap the Write Cell in a Retry Scope to handle Excel-is-busy."** A Retry Scope around branch-3 (loop thrash) waits a few seconds and tries again — the underlying Excel COM state is still corrupt, and the retry compounds the damage. Worse, a Retry Scope around branch 2 (formula syntax) retries an invalid formula and either succeeds spuriously (Excel parses differently on the retry, masking the bug) or fails identically (wasted job time). Use Retry only with a real recovery action (re-open the workbook, reset COM state) AND only after diagnosing the underlying branch.
+
+- **"Use `Continue On Error: True` on the Write Cell so the workflow doesn't fail."** Silently suppresses every fault surface — protected sheet, bad formula, missing cell reference, locked file — and the job completes "successfully" while producing wrong outputs. Branches 4 (sheet missing) and 5 (protection) most commonly drift into this anti-pattern because the failure looks "expected" when the workbook structure shifts. Treat any Excel write failure as a data-correctness incident, not a flake.
+
+## Prevention (cross-branch)
+
+- Pick one Excel surface per workflow and stay on it. New workflows: prefer Modern `Use Excel File` + nested Modern activities (`Write Cell` inside the scope). Existing workflows: do not mix Classic Workbook activities with Modern scopes — the surfaces own files differently and conflict.
+- For any cell-by-cell write pattern, prefer Read Range → in-memory DataTable mutation → Write Range. Reserve `Write Cell` for single targeted writes (a header, a status flag, a timestamp) — not for bulk data.
+- Validate formula strings before passing to Write Cell. Log the resolved formula; eyeball the separators and quote-escaping; consider building formulas via a helper function that asserts the comma-separator rule.
+- Validate configured `SheetName` and `Cell` against the workbook's actual sheets / defined names at job start (`Get Workbook Sheets` + a quick `Read Cell` smoke test on the target). Fail fast with a clear message instead of letting a generic BusinessException surface mid-workflow.
+- Author workbooks consumed by UiPath without sheet- or workbook-level protection when possible. If protection is required for human consumers, scope it to specific cell ranges and leave the Robot's target cells unlocked.
+- Keep `UiPath.Excel.Activities` updated on a known-good version across the automation host fleet. Mismatched versions across hosts produce intermittent failures that look like branch 3 (Excel busy) but are package bugs; pinning the version in `project.json` and verifying it on each host eliminates this confound.
+- Set `Auto Save: False` on `Use Excel File` for workflows that write inside loops; explicit `Save Workbook` outside the loop avoids per-iteration disk pressure.
+
+## Related
+
+- Branch 4 (sheet not found) shares its diagnostic with [`read-range-sheet-not-found.md`](./read-range-sheet-not-found.md) — the same investigation steps and resolutions apply on the write side.
+- Branch 1's external-locker variant shares its diagnostic with [`read-range-file-locked.md`](./read-range-file-locked.md) — orphan EXCEL.EXE, user editing, network-share locks, AV/EDR scanners, and concurrent jobs all surface identically on Write Cell.
+- For shared / cloud Excel workbooks accessed via Microsoft Graph rather than the local filesystem, see [`../../o365-activities/overview.md`](../../o365-activities/overview.md) — the Write Cell equivalents on the cloud surface have entirely different fault modes (auth, throttling, eTag conflicts) covered there.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/summary.md

@@ -15,3 +15,8 @@
 | Lookup Range — Object Reference Not Set | Medium | `NullReferenceException` from a missing sheet/range name or the activity running outside an Excel scope | [lookup-range-null-reference.md](./playbooks/lookup-range-null-reference.md) |
 | Lookup Range — Invalid Range or Value | Medium | `Range` set to `""` instead of blank, malformed A1 reference, unescaped wildcards, or a text-vs-number type mismatch in the search value | [lookup-range-invalid-range.md](./playbooks/lookup-range-invalid-range.md) |
 | Lookup Range — Silent Miss Against a Formula Cell | Medium | Target value is the *computed* result of an Excel formula; Interop reads a stale/null cached value or fails to re-evaluate, so the lookup returns null even though the displayed text matches | [lookup-range-formula-cells.md](./playbooks/lookup-range-formula-cells.md) |
+| Read Range — File In Use By Another Process | Medium | Workbook held open by another process (user Excel UI, orphan `EXCEL.EXE`, network-share lock on a different host) so the activity cannot acquire the file (`System.IO.IOException: The process cannot access the file '<path>' because it is being used by another process.`) | [read-range-file-locked.md](./playbooks/read-range-file-locked.md) |
+| Read Range — Sheet With Specified Name Does Not Exist | Medium | The workbook opened successfully but the configured `SheetName` does not match any sheet in the workbook (`UiPath.Excel.BusinessException: The sheet with the name '<name>' does not exist.`). Causes: typo, case mismatch on the OpenXML provider, sheet renamed or deleted upstream, leading/trailing whitespace, look-alike Unicode characters, or a dynamic `SheetName` expression resolving to the wrong value at runtime | [read-range-sheet-not-found.md](./playbooks/read-range-sheet-not-found.md) |
+| Read Range — Workbook File Or Directory Not Found | Medium | The configured `WorkbookPath` does not resolve to an existing file at runtime (`System.IO.FileNotFoundException: Could not find file '<path>'.` or `System.IO.DirectoryNotFoundException`). Causes: file moved/deleted upstream, UNC share unreachable, relative path resolved against wrong CWD, drive letter not mapped under the Robot's session, OneDrive/SharePoint Files-On-Demand placeholder, or extension/casing mismatch on case-sensitive shares | [read-range-file-not-found.md](./playbooks/read-range-file-not-found.md) |
+| Read Range — NullReferenceException / TargetInvocationException From Inside Activity | Low | The workbook opens but a generic .NET runtime exception fires during cell / range / formula / formatting parsing (`System.NullReferenceException` or `System.Reflection.TargetInvocationException` with no cell pointer). Possible causes: Microsoft Purview / AIP sensitivity label blocking the Robot user, workbook structural corruption (often from non-Excel writers like `openpyxl`), broken named range or formula reference (`#REF!`), unsupported OpenXML feature requiring COM, or heavy conditional formatting / parser scale limit. Low-confidence: error wording does not distinguish branches; diagnosis usually requires manual workbook inspection | [read-range-null-reference.md](./playbooks/read-range-null-reference.md) |
+| Write Cell Failures | Medium | `Write Cell` (Classic Workbook, Classic `Excel Application Scope`, or Modern `Use Excel File`) fails to write a value or formula. Symptoms surface as `System.IO.IOException` (file lock), `UiPath.Excel.BusinessException: ... wrong format, or Excel is busy` (formula syntax OR Excel COM state thrash — same wording, two causes), `BusinessException: ... sheet with the name '<x>' does not exist`, `COMException` about protected sheet / read-only workbook, or `BusinessException: ... cell reference '<x>' is invalid`. Causes: workbook locked OR Classic/Modern scope conflict (Classic Workbook activity racing a surrounding Modern scope on the same file), formula syntax (comma vs. semicolon separators, unescaped inner quotes, add-in-dependent functions), loop-induced Excel COM thrash when Write Cell runs cell-by-cell inside a tight loop, sheet name mismatch (same diagnostic as read-range-sheet-not-found), protected sheet / workbook / Read-only Mode scope, or invalid A1 cell reference / unknown named range. Includes anti-patterns section rejecting blanket Kill-Process-for-EXCEL, Retry-Scope-around-bad-formula, and Continue-On-Error suppression | [write-cell-failures.md](./playbooks/write-cell-failures.md) |

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/investigation_guide.md

@@ -23,3 +23,4 @@ When testing hypotheses for UI Automation issues, gather and verify these before
 5. **Execution context** — check if running attended vs unattended, screen resolution, RDP session state — these affect UI element visibility
 6. **Package version** — confirm `UiPath.UIAutomation.Activities` package version; behavior differs across versions
 7. **Enclosing scope container configuration** — for activities inside a scope container (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`, `Attach Window`, `Attach Browser`, etc.), open the workflow XAML and capture the container's `AttachMode`, `OpenMode` (defaults to `IfNotOpen` when absent), and `TargetApp.{Selector,Url}` values. The scope container determines which application instance/page the inner selector resolves against — a misconfigured scope makes a structurally correct selector fail (e.g., card attaches to an unintended existing tab via `AttachMode=ByInstance` + default `OpenMode=IfNotOpen` + a loose `TargetApp.Selector`). Do not confirm a selector-failure hypothesis before naming the scope container's configuration.
+8. **Silent no-op check** — if a UI activity completed `Successful` but its effect did not occur (e.g. the click never happened), check **Verify Execution** on that activity. An absent or target-less Verify (`VerifyOptions` with a Mode but no verification target) lets a wrong-target / wrong-page no-op pass without faulting — so a "succeeded but did nothing" report is usually a missing Verify, not a missing exception. See [playbooks/scope-container-wrong-page.md](./playbooks/scope-container-wrong-page.md).

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/overview.md

@@ -29,10 +29,26 @@ When a robot executes a UI activity (Click, Type Into, Get Text, etc.), it uses
 - **UiElementNotFoundException** — UI element lookup failed (similar to selector not found, different internal path)
 - **ElementNotInteractableException** — element was found but can't be clicked/typed into (hidden, disabled, covered by overlay)
 - **UiNodeDisabledElementException** — element was found but is disabled and the activity's `AlterIfDisabled` property is not `True`. Driver HRESULT `E_UINODE_CANNOT_ALTER_DISABLED_ELEM` (0x8004027D). Raised by interaction activities `NClick`, `NTypeInto`, `NSetText`, `NCheck`, `NSelectItem`, `NSAPClickPictureOnScreen`.
+- **VerifyActivityExecutionException** — activity's primary action succeeded but its `VerifyOptions` post-condition assertion did not hold within the verify retry window. Thrown by `VerifyExecutionService`, not COM-friendlied. Raised by `NClick`, `NHover`, `NKeyboardShortcuts`, `NTypeInto`. Multiple friendly messages route to distinct cause branches (`ExceptionCheckActivity`, `ExceptionVerificationTargetNotFoundOrInvalid`, `ExceptionVerificationTextNotSupported`, `ExceptionVerificationImageCouldNotBeRetrieved`, `ExceptionRecoveredButValidationFailed`, plus NTypeInto-specific text-match keys).
 - **NodeNotFoundException** — DOM or UI tree node missing
+- **NodeAmbiguousException** — selector matched more than one element. Distinct from `NodeNotFoundException` (zero matches): ambiguous = multiple matches.
 - **TimeoutException** — activity exceeded its wait time (ambiguous — could be UI or non-UI)
 - **ImageOperationException** — image-based UI automation failure
 - **ScreenScrapingException** — screen scraping activity failure
+- **ApplicationNotFoundException** — scope-level failure from `NApplicationCard` (Use Application / Use Browser) when the target application can't be located **and** the scope's `OpenMode=Never`. Distinct from `ApplicationOpenException` (which fires when `OpenMode != Never` and launch failed) and `WrongTargetApplicationException` (selector matched the wrong process).
+- **UiAutomationException — "Cannot send input to UI element because it is outside of screen bounds."** — input activity (`NClick`, `NTypeInto`, ...) located the element but the destination coordinate is outside the runtime host's virtual screen. Wraps `COMException 0x800402bd` at `UiPath.UiNodeClass.Click`. Distinct from the selector-failure family — element was resolved, coordinate was rejected. See [click-coordinate-off-screen.md](./playbooks/click-coordinate-off-screen.md).
+
+UIAutomationNext (`N*`) activities also raise these more specific exceptions:
+
+- **RuntimeTimeoutException** — modern activity timeout ("Activity execution exceeded the set timeout."). A UI timeout can also surface as **NodeNotFoundException** when the element never appeared within the timeout window.
+- **ApplicationOpenException** — a `Use Application/Browser` scope with `Open` ≠ `Never` tried to launch the app and the launch failed ("Could not open target application.")
+- **WrongTargetApplicationException** — the identified element belongs to a different application/browser than the scope's target
+- **BrowserFailedToNavigateToUrlException** / **BrowserInvalidURLException** — `Go To URL` could not navigate (failed navigation, invalid/empty URL, or a local `file://` blocked on Chromium)
+- **InvalidNodeException** / **UiNodeUninitializedElementException** — the element went invalid/stale between being found and acted on
+- **TargetFoundButNotVisibleException** — element found but its visibility did not match what the target expected
+- **TargetNotFoundBrowserBlockedException** — element could not be reached because a dialog is blocking the browser
+- **UiNodeHasNoItemsException** — Select Item's target container had no items
+- **UiAutomationException (activity configuration)** — an activity rejected an invalid property value (e.g. Mouse Scroll `Movement units` < 1, Keyboard Shortcuts empty/invalid sequence, Take Screenshot missing `File name`/`Saved image`, Go To URL / Inject Js Script missing required input)
 
 ## Features
 

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/activity-configuration-error.md

@@ -0,0 +1,42 @@
+---
+confidence: high
+---
+
+# Activity Configuration Error — Invalid Property Value
+
+## Context
+
+A UI Automation activity faulted on its own property validation, before (or independent of) finding the target: a required input was empty or a value was out of range. The exception names the property, so the cause is the configuration of that activity.
+
+What this looks like — one of these messages, by activity:
+- **Mouse Scroll** (`NMouseScroll`):
+  - `Value for property [Movement units] can not be lower than 1.` — `Movement units` was 0 or negative.
+  - `Searched element Target or Input UI Element must be set when Scroll type is set to Until element is found.` — "scroll until found" was selected with no searched-element target/input.
+  - `Unable to find the searched element.` — scrolling completed without ever finding the configured searched element.
+- **Keyboard Shortcuts** (`NKeyboardShortcuts`): `Invalid or empty shortcut sequence.` — no keys, or an unparseable key combination.
+- **Take Screenshot** (`NTakeScreenshot`):
+  - `'File name' can not be null, empty or whitespace.` — saving to file with no `File name`.
+  - `Required argument 'Saved image' was not provided.` — saving to an image output with no `Saved image` argument bound.
+
+What can cause it:
+- A property left at an invalid value (Movement units < 1, empty shortcut, empty file name).
+- A property fed by a variable/expression that evaluates to empty/zero at runtime because an upstream step did not populate it.
+- A mode/option chosen without its dependent input (scroll-until-found without a searched element; save-to-file without a file name; save-to-image without an output argument).
+
+What to look for:
+- The message names the property and the activity — read that property's configured value in the workflow.
+- If the value comes from a variable/expression, check what produced it.
+
+## Investigation
+
+1. From the failed job, capture the exact message (it names the property), the activity, and the workflow.
+2. Open the activity and read the named property's value.
+3. If the property is bound to a variable/expression, trace the upstream step that should set it; an empty/zero value usually means that step did not run or returned nothing.
+4. For mode-dependent inputs (Mouse Scroll "until element is found", Take Screenshot save mode), confirm the dependent input is provided for the selected mode.
+
+## Resolution
+
+- **Out-of-range/empty literal:** set a valid value on the activity (Movement units ≥ 1, a non-empty shortcut sequence, a file name / output argument).
+- **Empty from upstream:** fix the upstream step/variable that should populate the property — do not hard-code a literal to mask a missing producer unless the value is genuinely static.
+- **Mode missing its input:** provide the dependent input for the chosen mode (a searched-element target for scroll-until-found; a file name for save-to-file; a `Saved image` output for save-to-image).
+- **Mouse Scroll "Unable to find the searched element":** the searched element never appeared while scrolling — confirm the element exists on that view and is reachable by scrolling; if it should appear only after an earlier step, fix that step. Increase the searched-element timeout only if the element genuinely appears late.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/ambiguous-selector.md

@@ -0,0 +1,131 @@
+---
+confidence: high
+---
+
+# Ambiguous Selector — Target Matched Multiple Elements
+
+## Context
+
+A UI Automation Next activity threw `NodeAmbiguousException` because its target selector matched more than one element in the live UI tree. The target-find service walks the tree, accumulates every node satisfying the selector, and refuses to act when the result set has more than one. The activity never dispatches — no click, no key, no read.
+
+Applies to every UIAutomationNext activity that resolves a target before acting:
+
+- `NClick`, `NTypeInto`, `NCheck`, `NHover`, `NHighlight`, `NSetFocus`
+- `NGetText`, `NSetText`, `NGetAttribute`
+- `NSelectItem`
+- `NCheckElement`, `NCheckState`
+
+What this looks like:
+
+- Exception class: `UiPath.UIAutomationNext.Exceptions.NodeAmbiguousException`
+- Friendly message (the only one — this exception carries a static resource string with no placeholders):
+  > Multiple similar matches found.
+  >
+  > Could not uniquely identify the user-interface element for this action.
+  > Edit the element, run Validation, and add anchors in order to ensure the element is uniquely identified.
+- Resource key: `Strings.NodeNotFoundMultipleMatches`
+- Stack origin: the find phase of the activity (no `VerifyExecutionService` frames, no Healing Agent recovery frames — the find phase short-circuits before either runs).
+- Fault duration is short (typically under the activity `Timeout` — once the ambiguity is detected the find service does not retry).
+- The exception message does NOT include the offending selector — you must read the workflow source to recover it.
+
+What can cause it:
+
+- Selector is too generic — no anchor, no parent context, no `idx=`. Common authoring mistakes: `<webctrl tag='BUTTON' />`, `<webctrl tag='INPUT' type='submit' />`, `<wnd cls='Button' />`.
+- The UI legitimately has repeated controls (table rows, card grid, list items, paginated wizard steps) and the selector does not narrow to one row/card/page.
+- Multiple windows or tabs of the same application are open and the selector does not include a window-scope qualifier (`<html app='msedge.exe' title='Specific Title' />`).
+- Dynamic attributes drifted — the attribute that was unique at design time is no longer unique at runtime (regenerated id, A/B-tested layout duplicated a control).
+- Iframe / shadow-root traversal that pulls the same logical DOM tree into the search twice.
+- A previous activity (e.g., an opened dialog) introduced a duplicate of the target element on top of the existing one.
+
+What to look for:
+
+- Confirm the exception class is `NodeAmbiguousException`. If it is `NodeNotFoundException` / `SelectorNotFoundException` / `UiElementNotFoundException`, the selector matched ZERO elements — use the `selector-failure-*.md` playbooks instead. Ambiguous = multiple matches; failure = no matches.
+- Healing Agent **explicitly bypasses** this exception. Its recovery pipeline (`FindAlternativeOriginalTargetHiddenStrategy`) checks for `NodeAmbiguousException` and returns immediately, producing no recovery data. If you see `HealingAgentBehavior=Job` or `=Card` on the activity and no recovery payload for this fault, that is correct behavior — not an HA misconfiguration. Do NOT treat this as a `no-recovery-data.md` case.
+- The exception message ALONE does not identify the duplicate. To diagnose you must:
+  - Read the workflow source to get the selector
+  - Open the target page at the time of failure (or its `InformativeScreenshot` if attached to the `TargetAnchorable`) and count how many elements satisfy the selector
+- The activity `Timeout` is irrelevant. Extending it does not give the find service more time to disambiguate — the service has already decided as soon as >1 match is found.
+
+## Investigation
+
+1. From the failed job, capture the exception class, faulting activity, and workflow file.
+2. Open the workflow source. Locate the failing activity by `DisplayName` or `IdRef`. Read its `Target` block:
+   - The active selector — check the `SearchSteps` attribute on the `TargetAnchorable` and read whichever selector matches: `SearchSteps='FullSelector'` → `FullSelectorArgument`; `SearchSteps='FuzzySelector'` → `FuzzySelectorArgument`. One of these will be set, the other typically empty. Do not assume `FullSelectorArgument` is always populated.
+   - `ScopeSelectorArgument` — the window/scope wrapper (often just the app + window title)
+   - `BrowserURL` — for web targets, the URL the target lives on
+   - `InformativeScreenshot` — design-time screenshot of the intended element (filename only — file may not be in the repo)
+3. Inspect the selector specificity. Decompose attributes into "specific" (`aaname`, `aria-label`, stable `id`, `name`, `data-testid`, application-owned `data-*`) vs. "generic" (`tag`, `type`, `cls`, `role`). A selector with only generic attributes against a page that has repeated patterns is the canonical ambiguous case.
+4. Determine the duplication source. Classify the failure:
+   - Repeated UI pattern (multiple rows / cards / list items)
+   - Multiple windows / tabs of the same app open simultaneously
+   - Dynamic attribute drift (id was stable at design time, regenerated at runtime)
+   - Iframe / shadow-root double traversal
+   - Overlay / dialog opening a duplicate of the underlying control
+5. Confirm the duplication is reachable from the activity's scope at runtime. If a sibling activity opens a dialog before the failing activity runs, the duplicate may only exist transiently — the fix is to gate on the dialog being closed, not to narrow the selector.
+6. Confirm the activity is NOT wrapped in a Retry Scope on `NodeAmbiguousException`. If it is, retrying does not help — the ambiguity is structural, not transient. The retry block must be removed and the selector fixed at source.
+
+## Resolution
+
+### Decision tree
+
+Walk this tree from the top. Stop at the first branch that matches.
+
+1. **Is the selector relying only on generic attributes** (`tag`, `type`, `cls`, `role`) with no specific identifier?
+   - YES → branch **(A)**. Selector is too generic — add a specific attribute.
+   - NO → continue.
+
+2. **Does the failure happen against a repeated UI pattern** (table rows, card grid, list items, paginated forms)?
+   - YES → branch **(B)**. The selector matches the pattern but not a specific instance — narrow by anchor or index.
+   - NO → continue.
+
+3. **Are multiple windows / tabs of the same application open** when the activity runs?
+   - YES → branch **(C)**. Narrow the `ScopeSelectorArgument` to the specific window — or attach to the scope explicitly via `NApplicationCard`.
+   - NO → continue.
+
+4. **Was the unique attribute stable at design time but drifts at runtime** (regenerated id, dynamic GUID, A/B-tested attribute)?
+   - YES → branch **(D)**. Replace the drifting attribute with a stable one — or use a wildcard / regex match.
+   - NO → continue.
+
+5. **Does the page contain iframes or shadow-roots that traverse the same logical DOM twice**?
+   - YES → branch **(E)**. Anchor the selector inside the correct frame.
+   - NO → continue.
+
+6. **Default — an overlay / dialog opened a duplicate of the target** → branch **(F)**. Gate the activity on the dialog being closed before the action runs.
+
+### Branches
+
+- **(A) Selector too generic — add a specific attribute.** The selector uses only generic attributes (`tag`, `type`, `cls`, `role`) that match many sibling controls. Open the target in Studio's Selector Editor or Object Repository. Add the first stable, specific attribute the target exposes: `aaname` / `aria-label`, `name`, `id` (only if it does not drift), `data-testid`, application-owned `data-*`. Re-run Validation in Studio to confirm "single match". Example: change `<webctrl tag='INPUT' type='submit' />` to `<webctrl tag='INPUT' type='submit' name='btnK' />` (Google Search) to disambiguate from the "I'm Feeling Lucky" submit on the same page.
+
+- **(B) Repeated UI pattern — narrow by anchor or index.** The selector matches a pattern that legitimately repeats (rows, cards, list items). Two viable fixes:
+  - **Use an anchor**: wrap the target with a `Find Anchor` (or Object Repository anchor) that locks the search to a specific neighbor (the row's first cell with a known label, the card's title, the section header above the action button). Anchors are the preferred Object Repository pattern because they survive row reordering.
+  - **Use `idx='N'`** in the selector if the position is stable across runs (e.g., always the first row). Fragile under list reordering.
+
+  Do NOT loop over every match and act on each — that is a different operation, surfaced via `NForEachUiElement`, not a fix for `NodeAmbiguousException`.
+
+- **(C) Multiple windows / tabs open — narrow window scope.** The selector's `ScopeSelectorArgument` was too generic — e.g., `<html app='msedge.exe' title='Google' />` matches every Edge window currently titled "Google". Fix one of:
+  - Narrow the `ScopeSelectorArgument` to a title pattern unique to the intended window.
+  - Attach to the application explicitly via an `NApplicationCard` opened on the intended window — actions inside the card inherit the card's scope and ignore other windows.
+  - If multiple windows of the same app are an expected and legitimate workflow state, surface that to the workflow author — the workflow needs an explicit "switch to window N" step before the action, not a tighter selector.
+
+- **(D) Dynamic attribute drift — use a stable attribute or wildcard.** The attribute that disambiguated at design time was regenerated, A/B-tested, or replaced at runtime. Symptom: a previously-working workflow starts failing with `NodeAmbiguousException` without any workflow change. Fix:
+  - Replace the drifting attribute with a stable one (`name`, `data-testid`, application-owned `data-*`).
+  - If no fully-stable attribute exists, use wildcard matching: `id='button_*'` or regex on the drifting portion. Validate that the wildcard still uniquely matches the intended element.
+  - Coordinate with the application team to add a stable test-id if the application is internal. UI automation against an app whose every attribute is generated is the actual problem.
+
+- **(E) Iframe / shadow-root double traversal.** The selector traverses into an iframe or shadow root that hosts the same logical DOM as the parent — the find service then matches both the original element and the duplicate inside the frame. Open the target page's DOM and identify which frame the intended element lives in. Anchor the selector explicitly: prepend an iframe selector segment (e.g., `<webctrl tag='IFRAME' aaname='specific-frame-name' />`) for iframe, or use the application's shadow-root selector. If the duplication is unintentional (the application's bug), report it — UI automation cannot reliably target an application that duplicates its own DOM into ambient frames.
+
+- **(F) Overlay / dialog duplicated the target — gate on dialog state.** A dialog, modal, or popup opened between a prior activity and the failing one, and the dialog hoists a copy of the underlying control. Symptom: ambiguity that only fires when a specific sibling activity ran just before. Fix:
+  - Add an `NCheckAppState` before the failing activity to wait for the dialog to close (`Disappears` mode).
+  - If the dialog is expected to stay open, narrow the selector to scope into the dialog's container only (the dialog's root has a distinguishing attribute — `role='dialog'`, `aria-modal='true'`, a specific class).
+  - Do NOT add a fixed `Delay` and hope the dialog dismisses on its own — race conditions reappear under load.
+
+### Anti-patterns
+
+The following are NOT valid fixes for `NodeAmbiguousException`:
+
+- **Increase the activity `Timeout`** — irrelevant. The find service has already decided as soon as >1 match is found; more time does not change the outcome.
+- **Switch `InteractionMode`** (Simulate / Hardware Events / ChromiumAPI / WindowMessages) — input mode applies to the action after the target is found. The target was never found uniquely; input mode does not enter.
+- **Enable Healing Agent on the activity / card / process** — Healing Agent explicitly bypasses `NodeAmbiguousException` (`FindAlternativeOriginalTargetHiddenStrategy` short-circuits when the exception type is detected). Turning HA on produces no recovery data and no fix.
+- **Wrap the activity in a try / catch and ignore the exception** — the action never happened; downstream workflow state is invalid.
+- **Wrap the activity in a Retry Scope** — ambiguity is structural, not transient. Retrying the same selector returns the same multiple matches every time.
+- **Add `idx='1'` unconditionally** — only valid in branch (B) when position is stable across runs. Doing it blindly hides selector drift and masks future regressions.