@uipath/skills 1.195.0 → 1.196.0

package/skills/uipath-troubleshoot/references/activity-packages/classic-activities/playbooks/ui-element-interaction-failed.md

@@ -0,0 +1,61 @@
+---
+confidence: medium
+---
+
+# UI Element Interaction Failed — Found but Action Did Not Succeed
+
+## Context
+
+A classic UI activity located its target element but could not perform the action on it, throwing
+`ElementOperationException`. Applies to `Click`, `Type Into`, `Send Hotkey`, and `Take Screenshot`.
+This is distinct from "element not found" — the selector matched, but the operation against the
+element failed.
+
+What this looks like:
+- `ElementOperationException` (the selector resolved, then the click/type/screenshot operation
+  failed)
+- The activity did not run for its full timeout — it found the element quickly, then failed on the
+  action
+
+What can cause it:
+- The element is disabled / read-only, so it cannot receive the click or text
+- The element is obscured by another window, a popup, a tooltip, or an overlay at the moment of the
+  action
+- The element (or its coordinate) is off-screen or scrolled out of view for hardware-event input
+- Focus was lost between locating the element and acting on it (another app stole focus, a dialog
+  appeared)
+- The chosen input method does not work for this element/technology (e.g. background/window-message
+  input on an element that only responds to hardware events, or vice versa)
+- `Take Screenshot`: the target window could not be brought to the foreground or rendered
+
+What to look for:
+- Whether the element is enabled and interactable at the moment of the action (not just present)
+- Whether a popup/overlay/another window covers the element
+- The input mode configured on the activity (simulate / window messages / hardware events) vs. the
+  target technology
+- Whether focus is stable while the workflow runs (no other automation or user interaction competing)
+
+## Investigation
+
+1. Confirm from logs the failure is an interaction failure (element resolved) rather than a
+   not-found/timeout.
+2. Reproduce and observe the target at the moment of the action — is it enabled, fully visible, and
+   on screen?
+3. Check for overlays, modal dialogs, or another window covering or stealing focus from the target.
+4. Review the activity's input method against the application technology; try the alternative input
+   method to see if the action succeeds.
+5. For `Take Screenshot`, verify the target window can be brought to the foreground (not minimized,
+   not on a disconnected session).
+
+## Resolution
+
+- **If the element is disabled:** fix the upstream step so the element is enabled before the action
+  (complete the prerequisite that activates it); do not force input on a disabled control.
+- **If an overlay/dialog/another window covers or steals focus:** dismiss/handle the blocker in the
+  workflow before the action.
+- **If the input method is wrong for the technology:** switch the activity's input method to one the
+  target supports.
+- **If the element is off-screen:** ensure it is scrolled/brought into view before acting (or use an
+  input method that does not require an on-screen coordinate).
+- **If `Take Screenshot` cannot foreground the window:** run in an interactive session and ensure the
+  window is restorable.

package/skills/uipath-troubleshoot/references/activity-packages/classic-activities/playbooks/ui-element-not-found.md

@@ -0,0 +1,64 @@
+---
+confidence: medium
+---
+
+# UI Element Not Found — Classic UI Activity
+
+## Context
+
+A classic UI Automation activity could not locate its target element within the timeout. Applies to
+`Click`, `Type Into`, `Send Hotkey`, `Take Screenshot`, `Wait UI Element Appear`, `Attach Browser`
+(Browser Scope), `Attach Window` (Window Scope), and `Close Tab`.
+
+What this looks like:
+- `SelectorNotFoundException`, or an error message such as "Cannot find the UI element corresponding
+  to this selector"
+- The activity ran roughly for its full timeout before failing
+- The failing activity carries a `Selector` / `Target.Selector` property
+
+What can cause it:
+- The application or window the selector points to is not open, or is on a different
+  screen/session/desktop than the robot
+- Selector drift — the application changed (a UI update, a different version, a different language)
+  so one or more selector attributes no longer match
+- The selector depends on dynamic attributes (auto-generated `id`, `idx`, title text with a counter)
+  that differ at run time
+- The activity is inside the wrong scope — an `Attach Browser`/`Attach Window` (or `Open ...`) that
+  attached to a different window than the inner selector expects
+- The element exists but only appears after a delay, and the activity's timeout is shorter than that
+  delay
+- An earlier step in the workflow failed silently (navigation didn't happen, login wasn't completed)
+  so the expected screen is not showing
+
+What to look for:
+- The exact selector on the failing activity (from the XAML or the job's verbose logs)
+- Whether the target application was actually open and focused at the moment of failure
+- Whether the failure is consistent or intermittent (intermittent → timing/readiness; consistent →
+  selector or scope)
+
+## Investigation
+
+1. Identify the failing activity and read its full selector from the XAML or the verbose execution
+   log.
+2. Confirm the target application/window was open and reachable when the activity ran — check earlier
+   steps in the same execution that should have launched or navigated to it.
+3. Compare the selector against the live application (UI Explorer / Selector Editor against the
+   running app). Identify which attribute(s) no longer match.
+4. Check whether any matched attribute looks dynamic (numeric suffixes, GUIDs, full title strings)
+   that would differ between runs.
+5. If the activity is inside a scope (`Attach Browser`/`Attach Window`/`Open ...`), verify that scope
+   attached to the intended window, not a different instance or a stale handle.
+6. Re-check whether the element appears only after a delay relative to the activity's timeout.
+
+## Resolution
+
+- **If the application/window was not open or not on the right screen:** fix the upstream step that
+  should have opened or navigated to it; do not point the activity at a window that isn't there.
+- **If a selector attribute no longer matches (selector drift):** repair the selector to match the
+  current application, preferring stable attributes over volatile ones.
+- **If the selector relies on dynamic attributes:** replace them with stable attributes or wildcards
+  so the selector survives across runs.
+- **If the scope attached to the wrong window:** correct the scope's selector so it attaches to the
+  intended window; the inner selector is fine.
+- **If the element appears only after a delay:** wait for the real readiness signal (the element/the
+  expected state) rather than padding the timeout blindly, and find why it is slow.

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

@@ -0,0 +1,24 @@
+# Classic Activities Playbooks
+
+**Overview:** [overview.md](./overview.md) — classic `UiPath.Core.Activities` (UI Automation + System/Core), failure families, and package boundaries
+
+Covers the **classic** UI Automation (`UiPath.UIAutomation.Activities`) and System/Core
+(`UiPath.System.Activities`) activities. For the modern "Next" UI activities see the
+**ui-automation** package; for `Get Asset` / `Get Credential` (incl. `Get Robot Asset/Credential`)
+see the **system-activities** package.
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| UI Element Not Found | Medium | A classic UI activity (`Click`, `Type Into`, `Send Hotkey`, `Take Screenshot`, `Wait UI Element Appear`, `Attach Browser/Window`, `Close Tab`) threw `SelectorNotFoundException` / "Cannot find the UI element corresponding to this selector" — the target was not located within the timeout. Selector drift, application not open/ready, or wrong scope. | [ui-element-not-found.md](./playbooks/ui-element-not-found.md) |
+| UI Activity Timeout | Medium | A classic UI activity threw `ActivityTimeoutException` ("Activity timeout exceeded") — the element or state was never reached. Includes `Wait UI Element Appear` (element never appeared) and `Wait Image Vanish` (image still present after the timeout). | [ui-activity-timeout.md](./playbooks/ui-activity-timeout.md) |
+| UI Element Interaction Failed | Medium | `ElementOperationException` from `Click` / `Type Into` / `Send Hotkey` / `Take Screenshot` — the element was located but the action could not be performed (disabled, occluded, off-screen, or focus lost between find and act). | [ui-element-interaction-failed.md](./playbooks/ui-element-interaction-failed.md) |
+| Browser Could Not Open or Attach | Medium | `BrowserOperationException` / invalid-browser error from `Open Browser`, `Close Tab`, or `Attach Browser` (Browser Scope) — browser not installed/launchable, extension missing/disabled, browser crashed, or wrong browser type for the communication method. | [browser-open-or-attach-failed.md](./playbooks/browser-open-or-attach-failed.md) |
+| Application Could Not Launch | Medium | `Open Application` / `Open Browser` failed to start the target. File/executable path not found, bad arguments, or "Both FileName and Arguments arguments are null" validation. The app never produced a window for the scope to attach to. | [application-launch-failed.md](./playbooks/application-launch-failed.md) |
+| UI Activity Configuration Error | High | Design-time / validation error before execution: two mutually-exclusive options both set ("Only one of the {0} and {1} options can be set" — e.g. SimulateClick + SendWindowMessages), conflicting `Selector` + `Browser`/`Window` on a scope, or a communication-method incompatibility on `Open Browser`. | [ui-activity-configuration-error.md](./playbooks/ui-activity-configuration-error.md) |
+| Image Target Not Found / Did Not Vanish | Medium | `Wait Image Vanish` (or other classic image automation) did not behave as expected: the image was never matched, or it was still present after the timeout. Sensitive to display scaling, resolution, theme, and design-vs-runtime rendering. | [image-target-not-found.md](./playbooks/image-target-not-found.md) |
+| File Operation Failed | Medium | `Rename File`, `Move File`, or `Append Line` faulted: "The source file does not exist.", "Destination should be a folder.", "File cannot be null", file already exists, path is a directory, access denied, or the file is locked by another process. | [file-operation-failed.md](./playbooks/file-operation-failed.md) |
+| Invoke Workflow / Start Triggers Failed | Medium | `Invoke Workflow File` (or `Start Triggers`) faulted: workflow file not found, argument name/type/direction mismatch, isolated/elevated/session validation error, persistence not supported, or the invoked child workflow itself threw. | [invoke-workflow-failed.md](./playbooks/invoke-workflow-failed.md) |
+| Invoke Code Failed | Medium | `Invoke Code` faulted: compilation failed ("No compiled code to run"), compilation errors in the snippet, unsupported language, or an exception thrown by the user's own code at run time. | [invoke-code-failed.md](./playbooks/invoke-code-failed.md) |
+| Add Queue Item Failed | Medium | `Add Queue Item` faulted: "\"Queue name\" may not be null or empty.", invalid item-information key characters, a duplicate item key, queue not found, or an Orchestrator permission / HTTP / timeout error. | [add-queue-item-failed.md](./playbooks/add-queue-item-failed.md) |
+| Kill Process Failed | Low | `Kill Process` faulted with "Encountered errors while trying to kill a process" — process not found, access denied (insufficient privileges or protected process), or errors across several matched processes. | [kill-process-failed.md](./playbooks/kill-process-failed.md) |
+| For Each Row Failed | Low | `For Each Row` faulted: the DataTable is null/uninitialized, the iterator (`CurrentRow`) variable name is invalid, or an activity inside the loop body threw on a particular row. | [foreach-row-failed.md](./playbooks/foreach-row-failed.md) |

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/read-range-file-locked.md

@@ -0,0 +1,142 @@
+---
+confidence: medium
+---
+
+# Read Range — File In Use By Another Process
+
+## Context
+
+A `UiPath.Excel.Activities` activity that opens a workbook (Read Range and the rest of the read/write family, plus the surrounding `Excel Application Scope` / `Use Excel File` scope) fails because another process is holding an exclusive lock on the workbook file. The activity cannot acquire the file and faults before any sheet or range parsing happens.
+
+What this looks like:
+- Activity fails with `System.IO.IOException: The process cannot access the file '<path>' because it is being used by another process.` The error wording is the .NET IO message — the activity passes it through with minimal wrapping.
+- Under Excel COM (Excel Application Scope or `Use Excel File` falling back to COM), the surface may also be `System.Runtime.InteropServices.COMException` with HRESULT `0x800A03EC` and Excel's own message about the file being locked for editing. Same root cause, different wrapper.
+- The path in the error is the workbook the activity was configured to open.
+- May be intermittent (the locker releases the file between job attempts and retries succeed) or persistent (a stuck process holds the lock indefinitely).
+- No sheet name, range address, or cell value appears in the error — failure happens at file acquisition, before parsing.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **User opened the workbook in Excel UI** — A human is editing the workbook in Microsoft Excel on the same host (or, for a network share, on any host that has the file open). Excel takes an exclusive write lock by default. Common on developer workstations and shared automation hosts.
+2. **Orphan `EXCEL.EXE` from a prior job** — A previous job left an `EXCEL.EXE` process running (typically because an `Excel Application Scope` was bypassed with `Continue On Error`, the workflow threw inside the scope without proper cleanup, or the executor was killed mid-run). The orphan still owns the file lock under the Robot's session. Symptom: file is locked but no human is using it; `EXCEL.EXE` appears in `tasklist` with no visible UI.
+3. **Network-share lock from a different host** — Workbook lives on a UNC path or mapped network drive, and another machine (a developer's workstation, a different Robot host, a SharePoint sync agent, an indexer) is holding the lock. Local host shows no `EXCEL.EXE`; lock is held elsewhere.
+4. **Concurrent Robot jobs racing on the same workbook** — Two or more jobs scheduled against the same workbook ran simultaneously; the first one's `Excel Application Scope` / `Use Excel File` is still open when the second one tries to acquire. Common pattern: triggers fire on overlapping schedules, or a queue dispatcher started multiple performers without per-workbook serialization.
+5. **Antivirus / EDR / indexer holding the file** — Defender, a third-party AV, Windows Search Indexer, OneDrive / SharePoint sync client, or a backup agent transiently opens the workbook for scanning. Lock is brief (seconds) but races with the activity's open call. Intermittent failures without any visible Excel instance are the fingerprint.
+6. **Hidden Excel instance owned by a different user session** — Excel was launched under a different Windows session (e.g., an admin RDP'd in earlier and left Excel running; a service account left an instance open under fast user switching). Task Manager shows `EXCEL.EXE` under "Users" → another session, not the current one.
+
+What to look for:
+- **The exact path in the error** — confirms the workbook the activity tried to open. Don't assume it matches the configured property — variable expressions may have resolved differently.
+- **`EXCEL.EXE` presence on the host at failure time** — strongest single signal. If present under the Robot user → branch 2 or 4. If present under a human user → branch 1. If absent locally but the file is on a UNC → branch 3 or 5.
+- **Lock owner across all sessions** — `handle.exe -a <path>` (Sysinternals) names the exact process and PID holding the file. Authoritative when available.
+- **Pattern across recent runs** — every run fails immediately → branch 2 or 4 (persistent holder). Intermittent, no pattern → branch 5 (transient scanner). Fails only during business hours → branch 1 (human editor).
+- **Workflow source** — look for `Continue On Error: True` on the surrounding `Excel Application Scope`, or a `Try Catch` that swallows scope exceptions. Either makes branch 2 (orphans) likely.
+- **Trigger / schedule configuration** — overlapping schedules or unbounded queue performers point at branch 4.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Confirm the activity and the path.** From the workflow source (and from `uip or jobs get <job-key> --output json` → `Info`), capture: the activity class (Read Range / Write Range / etc.), the scope it runs inside (`Excel Application Scope` vs. `Use Excel File`), the configured workbook path expression, and the resolved path from the error string. Mismatch between expected and resolved path is itself a finding (different scope cause, not this playbook).
+
+2. **Get the failing job and host.** `uip or jobs get <job-key> --output json` to capture `HostMachineName`, `RobotName`, `StartTime`, `EndTime`. The host is where the lock check has to run.
+
+3. **Check recent jobs on the same host / workbook.** `uip or jobs list --folder-path '<folder>' --process-name '<process>' --limit 20 --output json`:
+   - All recent runs on this host fail with the same IO exception → persistent holder (branches 2, 3, or a stuck branch 1). Skip to step 5.
+   - Mixed pass/fail with no pattern → likely branch 5 (transient scanner). Continue to step 4 but expect a clean snapshot.
+   - Failures clustered in business hours, passes outside → branch 1.
+   - Two or more jobs against the same workbook with overlapping `StartTime` / `EndTime` windows → branch 4.
+
+4. **Pattern: jobs that ran or scheduled around the failure window.** `uip or jobs list --folder-path '<folder>' --created-after <EndTime-10min> --created-before <EndTime+1min> --output json`. Look for sibling jobs that touch the same workbook — those are branch-4 candidates.
+
+5. **Host-side process snapshot.** On the host (or have the user run it the next time the failure occurs):
+   ```powershell
+   Get-Process EXCEL -ErrorAction SilentlyContinue |
+     Select-Object Id, SessionId, UserName, StartTime, MainWindowTitle
+   ```
+   - No `EXCEL.EXE` rows → branch 3 (lock is remote) or branch 5 (transient, already gone). Go to step 6.
+   - One or more `EXCEL.EXE` under the Robot user (same `SessionId` as the failing job's session, no `MainWindowTitle`) → **branch 2** (orphan).
+   - One or more `EXCEL.EXE` under a human user / different `SessionId` → **branch 1** (user editing) or **branch 6** (other session).
+   - Multiple `EXCEL.EXE` under the Robot user across overlapping `StartTime`s → branch 4 (concurrent jobs).
+
+6. **Exact lock owner (most authoritative).** If Sysinternals `handle.exe` is available on the host:
+   ```powershell
+   handle.exe -a '<workbook-path>'
+   ```
+   Names the exact PID and process holding the lock — including non-Excel processes (AV scanner, backup agent, OneDrive). Cross-reference the PID against `Get-Process` from step 5.
+   - Holder is `EXCEL.EXE` → confirmed branch 1, 2, or 6 per step 5.
+   - Holder is a scanner / sync / backup process → **branch 5**.
+   - Holder is on a different machine (network share) → handle.exe will not name it; go to step 7.
+
+7. **Network-share lock investigation (branch 3).** If the workbook is on a UNC path and the local host shows no holder:
+   - On the file server (if accessible): `Get-SmbOpenFile | Where-Object { $_.Path -like '*<workbook>*' }` (Windows file server) names the client machine and user holding the file.
+   - On a Linux/Samba server: `smbstatus --locks` or check the share's lock file.
+   - If the share is SharePoint via OneDrive sync: the local host's OneDrive client may be syncing the file; check `tasklist | findstr OneDrive` and the OneDrive activity log.
+
+8. **Cross-check workflow source for orphan-prone patterns (branch 2 confirmation).** Open the source:
+   - Is the failing scope `Excel Application Scope` with `Continue On Error: True`? That swallows scope-internal exceptions and may leave `EXCEL.EXE` running.
+   - Is there a `Try Catch` wrapping the scope where the `Catch` does not re-throw or close the scope?
+   - Is `Visible: True` set on the scope? Visible Excel instances are more likely to be left stranded after an executor crash.
+   - These together raise branch-2 confidence even after a one-off kill — the next run will produce a new orphan unless the workflow is fixed.
+
+The root cause is **which process holds the lock and why**. A confirmed finding names the holder (process name, PID, owning user / session / host) and one of the cause-branches.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — User has the workbook open in Excel UI:**
+  - On the host, close Excel (the human user closes the document, or coordinate a maintenance window).
+  - Prevention: do not edit production workbooks on automation hosts; move source-of-truth data files off shared automation hosts; for shared workbooks, use SharePoint / OneDrive with the `o365-activities` cloud surface instead of the desktop file.
+
+- **Branch 2 — Orphan `EXCEL.EXE` under the Robot user:**
+  - One-off kill (host, as the Robot user or admin):
+    ```powershell
+    Get-Process EXCEL | Where-Object { $_.SessionId -eq <robot-session-id> } | Stop-Process -Force
+    ```
+    Confirm the file is no longer locked (`handle.exe -a <path>` returns no holder) before re-running.
+  - Permanent fix: address the workflow pattern that produced the orphan:
+    - Remove `Continue On Error: True` from `Excel Application Scope`. Let the exception propagate so cleanup runs.
+    - In any `Try Catch` wrapping the scope, the `Catch` must dispose the scope or re-throw; do not silently suppress.
+    - Prefer `Use Excel File` over `Excel Application Scope` when the workbook does not require Excel-COM-only features — its disposal semantics are more robust.
+    - Set `Visible: False` on `Excel Application Scope` unless you are debugging interactively. Visible instances are harder to clean up after an abrupt executor exit.
+  - For chronic orphans on a host, add a startup task or a pre-job activity that kills stale `EXCEL.EXE` owned by the Robot user before the workflow begins.
+
+- **Branch 3 — Network-share lock from a different host:**
+  - Identify the locking host / user via `Get-SmbOpenFile` (Windows file server) or `smbstatus` (Samba). Coordinate with that user to close the file.
+  - As a tactical unlock on Windows file server: `Close-SmbOpenFile -FileId <id>` (administrator on the file server). Note this terminates the remote handle without giving the user a chance to save — confirm intent first.
+  - Prevention: move the workbook off a shared network path, or fence access to it with a check-out workflow (queue item per workbook, lock asset, or sentinel file). For SharePoint document libraries, switch to the `o365-activities` surface so file acquisition goes through Graph instead of an SMB lock.
+
+- **Branch 4 — Concurrent Robot jobs on the same workbook:**
+  - Serialize the jobs. Options:
+    - Switch the process to single-instance via a per-workbook lock asset (`uip or assets create lock-<workbook> ...`) acquired at job start and released at end. Workflow checks the asset and waits or fails fast.
+    - Use a queue with a single performer (concurrency 1) so two jobs cannot run together.
+    - Stagger triggers so schedules do not overlap.
+  - Verify by inspecting the triggers / schedule: `uip or triggers list --folder-path '<folder>' --output json` and confirm no two triggers fire the same process within the workbook's expected runtime window.
+
+- **Branch 5 — Antivirus / EDR / indexer / sync client:**
+  - Identify the holder via `handle.exe -a <path>` at failure time (the holder is transient — must capture during the lock window).
+  - Allowlist the workbook's directory in the AV/EDR product (Defender: add an exclusion for the folder; vendor-specific elsewhere).
+  - Stop Windows Search from indexing the automation data folder: Indexing Options → Modify → uncheck the folder.
+  - For OneDrive / SharePoint sync clients on automation hosts: either un-sync the folder (preferred — automation hosts should not run sync clients) or use Files-On-Demand and ensure files are downloaded before the job runs.
+  - Add a retry-on-`IOException` wrapper as a defensive measure (Retry Scope with 3 attempts, 5-second back-off) — masks transient scanner races without papering over a real holder.
+
+- **Branch 6 — Hidden Excel instance under a different user session:**
+  - Identify the session: `quser` on the host shows all active and disconnected sessions; the `Get-Process EXCEL` output from investigation step 5 names the session ID.
+  - If the session is a disconnected RDP from an admin: log it off (`logoff <session-id>`) after confirming with the session owner. The disconnected session's Excel goes with it.
+  - Prevention: dedicate automation hosts to the Robot; humans should not RDP in for ad-hoc work, and when they must, they should sign out (not disconnect) when done.
+
+## Prevention (cross-branch)
+
+- Do not store production workbooks on hosts where humans actively edit Excel. Either move the workbook off the automation host, or move the editing workflow off it.
+- Prefer `Use Excel File` over `Excel Application Scope` for new workflows. Disposal is more robust; OpenXML provider sidesteps Excel COM entirely when the workbook does not require COM-only features.
+- Never set `Continue On Error: True` on an Excel scope. If the scope fails, fail the workflow — orphan `EXCEL.EXE` is worse than a single failed run.
+- Set `Visible: False` on `Excel Application Scope` in production. Reserve `Visible: True` for interactive debugging.
+- For workbooks that multiple processes legitimately need to touch, serialize via a per-workbook lock asset, single-performer queue, or sentinel file. Do not rely on Excel's own lock to coordinate — its error surface is too noisy.
+- Allowlist the automation data folder in AV/EDR; exclude it from Windows Search indexing; do not run OneDrive / SharePoint sync clients on automation hosts.
+- For long-running automation hosts, add a pre-job cleanup step that terminates stale `EXCEL.EXE` owned by the Robot user before the workflow begins. Cheap, idempotent, and prevents branch-2 chains from cascading across runs.
+
+## Related
+
+- Other Excel Read Range failure fingerprints (sheet not found, file not found, null-reference on formatted files) are separate playbooks — see [`../summary.md`](../summary.md).
+- If the executor was killed mid-Excel-scope (and the orphan is the consequence rather than the cause), inspect the surrounding job's exit code via `uip or jobs get <key> --output json` — an executor-termination exit code on the parent job points at job-level investigation, not Excel.
+- 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/read-range-file-not-found.md

@@ -0,0 +1,140 @@
+---
+confidence: medium
+---
+
+# Read Range — Workbook File Or Directory Not Found
+
+## Context
+
+A `UiPath.Excel.Activities` Read Range (or any activity that opens a workbook) fails because the configured `WorkbookPath` does not resolve to an existing file on the host at runtime. The failure happens at the scope's open step, before any sheet or range parsing. The fingerprint is one of the .NET filesystem-resolution exceptions surfacing through the activity.
+
+What this looks like:
+- Activity fails with one of:
+  - `System.IO.FileNotFoundException: Could not find file '<path>'.` — the parent directory exists but the file does not.
+  - `System.IO.DirectoryNotFoundException: Could not find a part of the path '<path>'.` — one or more segments of the parent path do not exist.
+  - On UNC paths, an inner `System.IO.IOException` with `The network path was not found` or `The network name cannot be found` may surface instead — same root condition, network layer.
+- The path echoed in the error is the resolved path the runtime attempted to open. Capture it verbatim — it is the authoritative input.
+- Affects every activity that opens a workbook: `Use Excel File`, `Excel Application Scope`, `Read Range`, `Write Range`, `Create Workbook` (when targeting a directory that doesn't exist), and so on.
+- The error fires before sheet/range parsing — sheet name and range are irrelevant.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **File moved or deleted upstream** — the workbook existed when the workflow was authored but has been deleted, archived, or moved by a human or another process. Symptom: parent directory still exists (`FileNotFoundException`, not `DirectoryNotFoundException`); the file is simply gone.
+2. **UNC share unreachable** — workbook lives on a UNC path (`\\server\share\...`) and the share is not reachable from the Robot host at runtime. Causes: network outage, DNS failure, share permissions changed (Robot user no longer has read), server offline, VPN required but not connected. Symptom: error wording mentions network path / network name, OR the path resolves but the parent directory enumeration fails.
+3. **Relative path resolved against wrong CWD** — workflow uses a relative path (e.g., `Data\sales.xlsx`) or a path expression that depends on the runtime working directory. Studio runs from the project directory; Robot may run from a different CWD (typically `%LocalAppData%\UiPath\Packages\<process-name>\<version>\`). Symptom: error path shows an unexpected prefix (NOT the user's project folder), or shows just the relative segment.
+4. **Drive letter not mapped under the Robot's session** — workbook path uses a mapped drive letter (e.g., `Z:\Data\sales.xlsx`) that exists in an interactive user session but not in the Robot's unattended session. Mapped drives are per-session on Windows; the Robot service's session sees only its own drive mappings. Symptom: `DirectoryNotFoundException` on the drive root; the same path works when an admin RDPs in and runs it manually.
+5. **OneDrive / SharePoint placeholder (Files-On-Demand)** — workbook lives in a folder synced by OneDrive or SharePoint client with Files-On-Demand enabled. The file appears in Explorer (placeholder icon) but its content has not been downloaded locally. The Robot user's session may lack the OneDrive client (it runs only under the interactive user), so the placeholder cannot be materialized. Symptom: file appears present when checked via Explorer under an interactive admin, but `Test-Path` from the Robot user's session returns False, OR returns True but file size is 0 / pinned.
+6. **Extension or filename casing mismatch** — workflow references `Sales.xlsx` but the actual file is `Sales.xls`, `Sales.xlsm`, or `sales.xlsx`. Local NTFS is case-insensitive, so casing alone doesn't trigger this on a local path — but a SMB-mounted Linux share or a SharePoint document library can preserve case-sensitivity. Symptom: path appears to match but `FileNotFoundException` fires; explorer shows the file with different casing or extension.
+
+What to look for:
+- **The resolved path echoed in the exception** — the authoritative input. Don't trust the design-time expression alone; the runtime value may differ (especially for dynamic path expressions or relative paths).
+- **`FileNotFoundException` vs `DirectoryNotFoundException`** — file missing vs. directory missing (branch 3, 4, or 2 mid-path).
+- **UNC vs local path** — `\\server\share\...` points at branch 2; `C:\` at branches 1, 5, or 6; mapped drive letter (`Z:\`, `M:\`, etc.) at branch 4.
+- **Pattern across recent runs** — every run fails identically → persistent (branches 1, 2, 4, 6). Intermittent → branch 2 transient or branch 5 stale-sync.
+- **Whose session can see the file** — branches 4 and 5 are session-scoped. If an admin RDPs in and can see the file but the Robot job can't, those branches are likely.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Confirm the activity, configured `WorkbookPath`, and resolved path.** From workflow source: the activity (`Read Range` / `Use Excel File` / etc.) and the `WorkbookPath` expression — literal string, dynamic expression, or variable. From `uip or jobs get <job-key> --output json` → `Info`: the exception class (`FileNotFoundException` / `DirectoryNotFoundException` / wrapped `IOException`) and the resolved path echoed in the error. The resolved path is the authoritative runtime value.
+
+2. **Classify the path shape.** Categorize the resolved path:
+   - Absolute local (`C:\...`, `D:\...`) → branches 1, 5, or 6.
+   - UNC (`\\server\share\...`) → branch 2 (or 6 if the share is case-sensitive).
+   - Mapped drive letter (`Z:\`, `M:\`, etc. — any letter besides standard `C:` / `D:`) → branch 4.
+   - Relative or no-drive prefix (`Data\sales.xlsx`, `sales.xlsx`) → branch 3.
+
+3. **Identify which exception fired.** If `DirectoryNotFoundException` and the missing segment is the drive root → branch 4. If `DirectoryNotFoundException` and a middle segment is missing → branch 1 (parent deleted) or branch 2 (UNC unreachable). If `FileNotFoundException` (parent OK, file missing) → branch 1, 5, or 6 (continue).
+
+4. **Recent-jobs pattern.** `uip or jobs list --folder-path '<folder>' --process-name '<process>' --limit 10 --output json`:
+   - Every recent run fails with the same path → persistent. Continue with the branch identified above.
+   - Mixed pass / fail with no pattern → likely branch 2 (transient UNC) or branch 5 (OneDrive sync race).
+   - Failures clustered after a specific date → branch 1 (file deleted then) or branch 6 (file renamed then).
+   - Some Robot hosts succeed, others fail → branch 4 (per-host drive mappings) or branch 2 (per-host network reachability).
+
+5. **Workflow-source check for branch 3.** If the path shape is relative:
+   - Locate the `WorkbookPath` expression in the workflow source.
+   - Determine whether it depends on `Environment.CurrentDirectory`, `Directory.GetCurrentDirectory()`, `Path.GetFullPath(...)`, or a project-relative reference.
+   - The Robot's CWD when running an unattended job is typically the per-package directory under `%LocalAppData%\UiPath\Packages\` (or the system equivalent), NOT the project folder. Any relative path resolves against that root.
+
+6. **Host-side verification when CLI evidence is insufficient.** For branches 4 and 5 specifically, the Robot host's filesystem state at the moment of the failure is the authoritative evidence. Ask the user to run (on the Robot host, in the Robot user's session if possible):
+   ```powershell
+   # Confirm the resolved path
+   $path = '<resolved-path-from-error>'
+   "Test-Path: $(Test-Path $path)"
+   "Item exists: $((Get-Item $path -ErrorAction SilentlyContinue) -ne $null)"
+   if (Test-Path (Split-Path $path -Parent)) {
+       "Parent directory exists: True"
+       Get-ChildItem (Split-Path $path -Parent) | Select-Object Name, Length, Attributes
+   } else {
+       "Parent directory exists: False"
+   }
+   # For mapped drives (branch 4):
+   net use
+   # For OneDrive placeholders (branch 5):
+   Get-Item $path -ErrorAction SilentlyContinue | Select-Object Attributes
+   # 'Offline' or 'ReparsePoint' attributes indicate a Files-On-Demand placeholder.
+   ```
+
+7. **Branch-specific signals from host evidence (when step 6 runs):**
+   - `Test-Path` returns False and parent directory contains files but not this one → **branch 1** (file deleted) or **branch 6** (renamed). Compare directory listing against expected name; if a different-cased / different-extension file is present → branch 6.
+   - `Test-Path` returns False, parent directory does not exist, drive root does not exist → **branch 4** (drive not mapped).
+   - `Test-Path` returns False for the same path that an interactive user CAN see in Explorer → **branch 4** (per-session drives) or **branch 5** (placeholder).
+   - `Get-Item` shows `Attributes` containing `Offline` or `ReparsePoint` → **branch 5** (OneDrive placeholder).
+   - UNC root listing fails with `The network path was not found` → **branch 2**.
+
+The root cause is **why the path does not resolve** — not "the file is missing" generically. A confirmed finding names the configured path, the resolved path, and one of the cause-branches with evidence.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — File moved or deleted:**
+  - Confirm where the file went (moved to a new location, archived to a different folder, or genuinely deleted). Restore from backup or version history if deletion was unintentional (SharePoint / OneDrive: Version History; local filesystem: shadow copies, backup tape).
+  - If the file moved deliberately, update the `WorkbookPath` to the new location.
+  - Prevention: do not store production workbooks in folders that humans regularly reorganize. Use a dedicated automation-data directory with restricted write access (or a SharePoint library with a documented "do not move" convention).
+
+- **Branch 2 — UNC share unreachable:**
+  - Verify network reachability: `Test-NetConnection <server> -Port 445` from the Robot host.
+  - Check share permissions on the file server: the Robot user (or its group) must have at least Read on the share AND on the underlying NTFS.
+  - For transient outages, add a Retry Scope around the workflow's open step with exponential back-off (3 attempts, 30s / 60s / 120s).
+  - Prevention: do not put automation-critical workbooks on shares with unreliable connectivity. Either move to a more reliable share or migrate to SharePoint with the `o365-activities` cloud surface (uses Microsoft Graph, sidesteps SMB entirely).
+
+- **Branch 3 — Relative path resolved against wrong CWD:**
+  - **Best fix:** convert the relative path to an absolute path. Use a known anchor:
+    - An Orchestrator asset that holds the data folder path: `assetData & "\sales.xlsx"`.
+    - `Environment.GetEnvironmentVariable("UIPATH_DATA_DIR")` — a machine-scope env var that points to the data root.
+    - `Path.Combine(Environment.SpecialFolder.LocalApplicationData, "MyAutomation", "sales.xlsx")` for per-user data.
+  - **If you must keep a relative path,** anchor it explicitly with `Path.GetFullPath(Path.Combine(Directory.GetParent(Reflection.Assembly.GetEntryAssembly().Location).FullName, "Data", "sales.xlsx"))` — but absolute paths are more readable and less fragile.
+  - Prevention: ban relative `WorkbookPath` values in workflow review. Always anchor to an explicit base.
+
+- **Branch 4 — Drive letter not mapped under Robot session:**
+  - **Best fix:** use the UNC path directly (`\\server\share\subpath\sales.xlsx`) instead of the drive letter. UNC paths do not depend on per-session drive mappings.
+  - **If the drive letter is load-bearing** (e.g., a third-party tool also referenced by drive letter), persist the mapping for the Robot user: run `net use Z: \\server\share /persistent:yes /user:<robot-user>` once while logged in as the Robot user. Verify with `net use` afterwards.
+  - **Or use the Windows GPO "Drive Maps" startup script** scoped to the Robot user.
+  - Prevention: standardize on UNC paths for unattended Robot workflows. Drive letters are user-session abstractions and lead to "works on my machine" failures.
+
+- **Branch 5 — OneDrive / SharePoint placeholder:**
+  - **Best fix:** stop syncing the workbook locally; use the cloud surface. Switch the workflow to the `o365-activities` package: `Read Range` (Files / OneDrive) reads via Microsoft Graph against the cloud copy directly, bypassing the local placeholder problem entirely.
+  - **If local sync is required:** mark the file as "Always keep on this device" via Explorer right-click, OR disable Files-On-Demand for the automation data folder (`attrib -p +s <path>`).
+  - **For the underlying issue** (Robot session lacks the OneDrive client): run the OneDrive client under the Robot user's session, OR (preferred) move the workflow off the desktop OneDrive sync model entirely to the cloud surface.
+  - Prevention: do not place automation-consumed workbooks in OneDrive/SharePoint sync folders on Robot hosts. Either put them on a non-synced filesystem path or consume them via Graph from the cloud.
+
+- **Branch 6 — Extension or filename casing mismatch:**
+  - Update the `WorkbookPath` to match the actual filename verbatim, including extension and casing.
+  - On case-sensitive shares (Linux Samba, SharePoint document library accessed via WebDAV), the workflow MUST use exact-case names. Adopt a convention with the workbook publisher.
+  - Prevention: when the path is sourced from external data (queue item, asset, CSV), normalize the case at validation time and confirm the file exists before reading. Workbook publishers should not rename files without coordinating with downstream consumers.
+
+## Prevention (cross-branch)
+
+- Validate `WorkbookPath` at job start via `File.Exists(path)` (or an explicit pre-check activity). Fail fast with a clear message naming the resolved path AND its parent-directory listing.
+- Anchor every path. Avoid relative paths in unattended workflows; prefer absolute paths sourced from a single, documented anchor (asset, env var, or constant).
+- Prefer UNC over drive letters for shared workbooks.
+- Do not couple automation data to per-user OneDrive/SharePoint sync state on Robot hosts. Either keep automation data on plain filesystem paths or consume via the cloud `o365-activities` surface.
+- Treat path layout as a contract between the workbook publisher and the workflow. Document the expected location and naming; renames are breaking changes.
+
+## Related
+
+- Other Excel Read Range failure fingerprints (file-locked, sheet-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/read-range-null-reference.md

@@ -0,0 +1,119 @@
+---
+confidence: low
+---
+
+# Read Range — NullReferenceException / TargetInvocationException From Inside The Activity
+
+## Context
+
+A `UiPath.Excel.Activities` Read Range (or any activity that parses workbook content) fails with a generic .NET runtime exception thrown from inside the activity's parsing code — not from file acquisition or sheet resolution. The workbook opens (no `IOException`, `FileNotFoundException`, or `BusinessException`), but somewhere during cell / range / formula / formatting parsing the activity hits a condition it cannot handle, and the .NET runtime surfaces a wrapper exception with little or no cell-level pointer.
+
+> **Confidence: low.** Unlike the file-locked, sheet-not-found, and file-not-found playbooks, the fingerprint here does not distinguish cause-branches by error wording alone. All five branches below can produce the same `NullReferenceException` or `TargetInvocationException` text. Diagnosis usually requires opening the workbook manually and inspecting it visually — the agent should investigate via Orchestrator evidence to rule out the easy cases, then hand the user a list of host-side / workbook-side checks rather than guessing a branch.
+
+What this looks like:
+- Activity fails with one of:
+  - `System.NullReferenceException: Object reference not set to an instance of an object.` — most common, surfaces from cell / range / named-range / formula parsing.
+  - `System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.` — a wrapper around an inner exception that the activity's reflection-based dispatch caught and re-threw. The `InnerException` (visible in `or jobs get` Info if the stack is included) is the load-bearing detail.
+  - Provider-specific wrappers: `UiPath.Excel.ExcelException` or `DocumentFormat.OpenXml.OpenXmlPackageException` for OpenXML provider failures; `System.Runtime.InteropServices.COMException` for Excel COM provider failures.
+- The exception's stack trace originates inside `UiPath.Excel.Activities.*` or `DocumentFormat.OpenXml.*` — NOT inside `System.IO.*` (that points at file-not-found / file-locked) and NOT inside `UiPath.Excel.WorkbookActivities.ReadRangeImpl.ResolveSheet` (that points at sheet-not-found).
+- The error has no cell address, no sheet name, no range expression — it's a generic runtime exception. The agent cannot pinpoint cause from the error string alone.
+- The workbook opens successfully on a developer's machine via interactive Excel; the problem surfaces only under the workflow's parsing path.
+
+What can cause it (cause-branches — none distinguishable by error wording alone):
+
+1. **Sensitivity label (Microsoft Purview / Azure Information Protection)** — the workbook is labeled (Confidential, Highly Confidential, etc.) and the label policy blocks programmatic access for the Robot user. The interactive user has the label permission and can open the file; the Robot service, running under a different identity, does not. Symptom: NRE / TIE on open or first read; an interactive admin RDPing in CAN open the file and see content; if the Robot user opens an Excel instance manually, the workbook either refuses to open or opens with a banner requesting authentication.
+2. **Workbook structural corruption** — the XLSX file (a ZIP container) was edited by another tool that left structurally invalid XML, broken relationships, or truncated parts. Common sources: a python script that wrote the workbook with `openpyxl` and a bug; a Power Automate flow that saved partial output; a network copy that was interrupted; a manual ZIP edit. Symptom: NRE or `OpenXmlPackageException`; Excel itself may open the file with a "Repaired" notice and a list of issues.
+3. **Broken named range or formula reference** — the workbook contains a defined name (named range) that points at a deleted sheet or out-of-range cell, OR a formula references `#REF!` or a non-existent range. When the activity walks the workbook's defined names or evaluates formulas, the parser hits a null / unresolvable reference. Symptom: NRE during read; opening the workbook in Excel and pressing `Ctrl+F3` (Name Manager) reveals defined names with `#REF!` in their formula.
+4. **Unsupported OpenXML feature** — the workbook contains an Excel feature only the COM provider supports (legacy XLS-format pages, certain macro objects, embedded OLE objects, specific chart types, dynamic arrays in older OpenXML versions). The default OpenXML provider in `Use Excel File` cannot parse it and fails with NRE or TIE. Symptom: works under `Excel Application Scope` (or `Use Excel File` with `ReadFormatting: True` forcing COM); fails under default `Use Excel File`.
+5. **Heavy conditional formatting / scale-related parser limit** — the workbook has thousands of conditional formatting rules, very large defined-range pivot caches, or millions of cells with formatting metadata. The parser hits a memory or recursion limit during the read. Symptom: NRE late in parsing (after open succeeded); workbook is unusually large (several hundred MB or millions of populated cells); opening it manually in Excel is also slow.
+
+What to look for:
+- **The exception class and stack origin** — `NullReferenceException` vs. `TargetInvocationException` (and its inner exception if available). Stack origin inside `OpenXml.*` points at branch 4 or 2. Stack origin inside the activity's name-resolution code points at branch 3.
+- **Workbook size on disk** — branch 5 candidates are usually large (> 100 MB) or have very high populated-cell counts.
+- **Recent provenance of the workbook** — was it just downloaded? Was it generated by a script or Power Automate? Was it edited by hand? Branch 2 (corruption) clusters around freshly-written files.
+- **Whether the same workflow worked on a different host with Excel installed** — branch 4 (unsupported OpenXML feature) is the canonical "works on dev box, fails on Robot" pattern from the sheet-not-found playbook's branch 2, but for parsing features rather than case sensitivity.
+- **Whether the workbook has visible sensitivity / classification banners** — when an interactive user opens the workbook, do they see a Purview / AIP banner? Branch 1 fingerprint.
+- **`Get Workbook Sheets` behavior** — if it succeeds and returns sheet names but `Read Range` fails, the failure is mid-parse (likely branches 3, 4, or 5). If it fails too, the failure is at open / first-read (likely branches 1 or 2).
+
+## Investigation
+
+This is a low-confidence playbook — the agent's job is to rule out the easier branches via Orchestrator evidence, then hand the user a list of host-side / workbook-side checks. Do NOT guess a specific branch without strong evidence.
+
+1. **Confirm the activity and the workbook.** From `or jobs get`: the exception class, the resolved workbook path, and the `Info` field's full stack trace if available. From workflow source: the activity (Read Range / Read Cell / etc.) and the scope (`Use Excel File` vs. `Excel Application Scope`). Capture the configured `SheetName`, `Range`, and any non-default properties (`ReadFormatting`, `EditPassword`, password expressions).
+
+2. **Categorize the exception.** Stack origin and inner exception narrow the suspect branches:
+   - `OpenXmlPackageException` / stack inside `DocumentFormat.OpenXml.*` → branch 2 (structural corruption) or branch 4 (unsupported OpenXML feature).
+   - `COMException` / stack inside `Microsoft.Office.Interop.Excel.*` → likely branch 4 (COM-side parsing issue) or branch 5 (COM hitting memory limit).
+   - Plain `NullReferenceException` with stack inside `UiPath.Excel.Activities.*` → could be any branch; need more evidence.
+   - `TargetInvocationException` with an inner exception → unwrap and re-categorize on the inner.
+
+3. **Recent-jobs pattern.** `uip or jobs list --process-name '<process>' --limit 20 --output json`:
+   - All recent runs against the same workbook fail with the same exception → persistent (branches 1, 4, 5 candidates).
+   - Only the latest run fails after a workbook update → branch 2 (corruption from a recent write) or branch 3 (someone deleted the named range's referent recently).
+   - Some Robot hosts succeed, others fail → branch 1 (label permissions per Robot identity) or branch 4 (COM-installed vs. headless OpenXML).
+
+4. **Workflow-source check for branch 3.** If the failing activity references named ranges (e.g., `Range: "MyDataRange"`) or formulas that depend on cross-sheet references, branch 3 is plausible. Note the named range and ask the user to verify it via Excel's Name Manager (`Ctrl+F3`).
+
+5. **Provider check for branch 4.** If the scope is `Use Excel File` with no `ReadFormatting` / `EditPassword` / macro-related properties, the runtime uses OpenXML on a host without Excel installed. Ask the user to try the same workflow under `Excel Application Scope` on a host with Excel — if it succeeds there, branch 4 is confirmed.
+
+6. **Hand the user a workbook-inspection checklist.** Once Orchestrator evidence is exhausted and the branch is not clearly identified, give the user the manual checks needed to confirm the cause. Examples:
+
+   ```powershell
+   # Size and modification time on the host
+   Get-Item '<workbook-path>' | Select-Object FullName, Length, LastWriteTime, Attributes
+   ```
+
+   Then ask the user to do the following in Excel on a workstation with the workbook open:
+   - **Branch 1 check:** Look for a sensitivity / classification banner at the top of the workbook (Confidential, Highly Confidential, label-specific text).
+   - **Branch 2 check:** Open the workbook in Excel and look for a "Repaired" dialog or recovery log noting any issues with the file.
+   - **Branch 3 check:** Press `Ctrl+F3` (Formulas → Name Manager). List any named ranges whose `Refers to` column shows `#REF!`, `#NAME?`, or `#VALUE!`.
+   - **Branch 4 check:** File → Info → Inspect Workbook → Check for Issues → Check Compatibility. Note any "features not supported by earlier versions" — these are often features OpenXML cannot parse.
+   - **Branch 5 check:** File → Info → workbook size; count of sheets; count of populated cells (Ctrl+End on each sheet). If the workbook is > 100 MB or has more than ~1M populated cells, branch 5 is plausible.
+
+7. **If the workbook is regenerated by another process before this workflow reads it** (branch 2 cluster pattern): coordinate with the upstream owner. Have them save / write the workbook through Excel itself (rather than a third-party library) to produce structurally clean output.
+
+The root cause is usually identifiable via Excel inspection more than via Orchestrator. A confirmed finding names the specific issue found in the workbook (a `#REF!` named range; a sensitivity label; an unsupported feature flagged by Compatibility Checker; a file size indicating scale) — not just "the workbook is broken."
+
+## Resolution
+
+Map the branch identified via Investigation + workbook inspection to the fix:
+
+- **Branch 1 — Sensitivity label blocks the Robot user:**
+  - The cleanest fix is to grant the Robot user permission for the label (Microsoft Purview → Information Protection → Labels → policy → add the Robot user / group).
+  - If label permissions cannot be granted, ask the workbook owner to remove the label or apply a less restrictive label.
+  - Long-term: do not classify workbooks consumed by automation with labels that exclude the Robot identity. Document an exemption for automation identities.
+
+- **Branch 2 — Workbook structural corruption:**
+  - One-off recovery: open the workbook in Excel manually; let Excel's repair dialog clean up the structure; save as a new `.xlsx`. Update the workflow to point at the repaired file.
+  - Permanent fix: the upstream tool that wrote the broken file needs to be fixed. Common offenders: `openpyxl` writes without all required parts; manual ZIP edits; truncated network copies. Have the upstream owner write through Excel COM or a well-maintained library (e.g., latest `openpyxl` with `data_only=True` discipline; `ClosedXML`; Excel itself via VSTO).
+  - Prevention: validate workbook integrity at the boundary where the file enters the automation pipeline. A one-line Open Excel File scope as a smoke test rejects corrupt files before downstream processing.
+
+- **Branch 3 — Broken named range / formula reference:**
+  - Open the workbook in Excel → `Ctrl+F3` → identify and either delete or fix every named range that shows `#REF!` in `Refers to`.
+  - For formulas with `#REF!` cells: fix the formula or delete the formula if the referenced data is no longer needed.
+  - Update the workflow's `Range` expression if it referenced a deleted named range.
+  - Prevention: do not delete sheets or cells that named ranges depend on without first updating the named ranges. The workbook publisher should audit Name Manager after structural changes.
+
+- **Branch 4 — Unsupported OpenXML feature:**
+  - **Best fix:** simplify the workbook to use only OpenXML-supported features. Use Excel's `File → Info → Inspect Workbook → Check Compatibility` to identify the offending features; remove or replace them.
+  - **Or force the COM provider:** set `ReadFormatting: True` (or another COM-forcing property) on `Use Excel File`, requiring Excel installed on the Robot host. Equivalent to the case-mismatch fix in the sheet-not-found playbook.
+  - **Or migrate to legacy `Excel Application Scope`:** explicit COM-only path. Less portable, but rules out OpenXML feature gaps entirely.
+
+- **Branch 5 — Heavy conditional formatting / parser scale limit:**
+  - Reduce the workbook's size: remove unused conditional formatting rules (Home → Conditional Formatting → Manage Rules → delete unused rules); compress or remove pivot caches; split large workbooks into per-month or per-region files.
+  - Raise the Robot host's memory (branch 5 often correlates with `MemoryException` if logs are detailed; sizing the host against the workbook is the fix).
+  - If the data fits, switch to the cloud surface (`o365-activities` package): Microsoft Graph reads only the data, not the formatting metadata, and is more memory-efficient for very large workbooks.
+
+## Prevention (cross-branch)
+
+- Treat any workbook consumed by automation as a contract: agree on the file format (current `.xlsx`, no macros, no embedded OLE), the maximum size, and the source tool that writes it.
+- Validate at the boundary: a one-line `Get Workbook Sheets` smoke test on the workbook at job start, with a clear failure message, catches branches 1 / 2 / 4 immediately and produces a much cleaner diagnosis than the generic NRE.
+- Audit workbook size and Name Manager after structural changes — saves operators 30 minutes per support ticket.
+- Do not classify automation-consumed workbooks with sensitivity labels that exclude the Robot identity.
+- When choosing between `Use Excel File` (OpenXML default) and `Excel Application Scope` (COM only), be deliberate. OpenXML is more portable but supports fewer Excel features. COM is more capable but requires Excel installed and has higher orphan risk (see [`read-range-file-locked.md`](./read-range-file-locked.md)).
+
+## Related
+
+- Other Excel Read Range failure fingerprints (file-locked, sheet-not-found, file-not-found) 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). Graph reads sidestep most branches of this playbook (no OpenXML parsing on the Robot host; no local sensitivity-label evaluation).
+- The Excel.Activities package's behavior across versions can shift — for stack-trace-specific branches (especially branch 4), check `UiPath.Excel.Activities` release notes for the version in use and consider upgrading.