@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/excel-application-scope-failures.md

@@ -0,0 +1,118 @@
+---
+confidence: medium
+---
+
+# Excel Application Scope (Classic) COM-Interop Failures
+
+## Context
+
+The Classic `Excel Application Scope` (class `UiPath.Excel.Activities.ExcelApplicationScope`) opens a workbook through Microsoft Excel via COM Interop. Unlike the Modern `Use Excel File` card (which defaults to the OpenXML provider and only falls back to COM when COM-forcing properties are set), Classic is **COM-only** — every execution spins up an `Excel.Application` COM server on the host. That hard COM dependency produces a family of failures that are specific to the Classic surface and do not occur on a pure-OpenXML Modern card.
+
+This playbook covers the **COM-interop-environment** failures of the Classic scope: the host has Excel, but the COM layer between UiPath and `EXCEL.EXE` is broken, contended, or hijacked. Three surfaces:
+
+1. **COM registration corruption** — Excel IS installed, but the `Excel.Application` COM class / type library registration is broken (typically after an Office upgrade or repair). The scope throws "Make sure Excel is installed" even though Excel is present.
+2. **Workbook acquisition blocked** — an orphan `EXCEL.EXE` from a prior crashed job (or a user-opened instance) still holds the target workbook, so the scope can't acquire it.
+3. **COM Add-in interface clash** — a COM add-in loaded into the Excel instance (the UiPath Excel Add-in or a third-party add-in) corrupts the QueryInterface negotiation, producing an `InvalidCastException` on `System.__ComObject`.
+
+> **Out of scope — cross-reference, don't re-diagnose here.** Failures the Classic scope SHARES with the Modern card live in [`./excel-application-card-failures.md`](./excel-application-card-failures.md): true Excel-not-installed (host has no Excel at all → that playbook's branch 1), empty / illegal `WorkbookPath` (branch 2), COM/RPC races across MULTIPLE scopes without an `Excel Process Scope` (branch 3), a child activity dropped outside any scope — "must be placed inside Excel Application Scope" (branch 4), and sensitivity-label rejection (branch 5). This playbook's branches assume a SINGLE Classic scope whose own COM acquisition fails on a host that DOES have Excel installed.
+
+What this looks like — Classic Excel Application Scope COM-interop faults surface as one of these signatures:
+
+- `UiPath.Excel.BusinessException: Error opening workbook. Make sure Excel is installed.` with an inner `COMException` carrying `0x8002801D TYPE_E_LIBNOTREGISTERED` ("Library not registered") or `0x80040154 REGDB_E_CLASSNOTREG` **on a host where Excel IS installed** — the interop / type-library registration is broken. Branch 1.
+- `UiPath.Excel.BusinessException: Failed opening the Excel file. Possible reasons: file is corrupt, already used by another process or password protected.` — an orphan `EXCEL.EXE` or a user-owned Excel instance still holds the target workbook. Branch 2.
+- `System.InvalidCastException: Unable to cast COM object of type 'System.__ComObject' to interface type 'Microsoft.Office.Interop.Excel.<Interface>'. ... QueryInterface ... failed due to the following error: No such interface supported (Exception from HRESULT: 0x80004002 (E_NOINTERFACE))` — a COM add-in (commonly `UiPath.Integration.ExcelAddin`) hijacked or corrupted the interop interface. Branch 3.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **COM registration corruption (Excel present, interop broken)** — Excel is installed and launches interactively, but the `Excel.Application` CLSID or its type library (`TYPE_E_LIBNOTREGISTERED`) isn't correctly registered for COM activation. Almost always follows an **Office version change**: an in-place upgrade to Microsoft 365 / Office 2024 click-to-run, a side-by-side install of a second Office version, or an interrupted Office update / repair. Stale `TypeLib` keys from the previous Office build point at a version that no longer exists, so `CoCreateInstance` succeeds at the class level but interface/typelib resolution fails. The Classic scope rewraps the COM error as the canonical "Make sure Excel is installed."
+2. **Workbook held by another EXCEL.EXE** — the target workbook is locked. Two sub-cases: (a) an **orphan** `EXCEL.EXE` — a prior job's scope crashed or was force-killed and left a headless `EXCEL.EXE` owned by the Robot's session still holding the file; (b) a **user-owned** instance — someone has the workbook open in the interactive Excel UI on the same host (common on attended / RDP-shared machines). Either way the file handle is exclusive and the new scope can't open it.
+3. **COM Add-in interface clash** — when the scope launches `EXCEL.EXE`, Excel auto-loads its registered COM add-ins. A misbehaving add-in — frequently the `UiPath.Integration.ExcelAddin` (the Studio "Excel Add-in" used for design-time recording) loaded on a runtime host where it shouldn't be, or a third-party add-in — interferes with the interop proxy so the `QueryInterface` for `Microsoft.Office.Interop.Excel.Application` (or `Workbook` / `Worksheet`) returns `E_NOINTERFACE`. The marshaled `__ComObject` can't be cast to the expected interop interface and the scope throws `InvalidCastException`.
+
+What to look for:
+
+- **The exception class + inner HRESULT** — first signal. `BusinessException: Error opening workbook. Make sure Excel is installed.` + inner `0x8002801D TYPE_E_LIBNOTREGISTERED` (or `0x80040154` despite a confirmed install) → branch 1. `BusinessException: Failed opening the Excel file. ... already used by another process` → branch 2. `InvalidCastException` on `System.__ComObject` + `0x80004002 E_NOINTERFACE` → branch 3.
+- **Host Excel install state** — the fork between this playbook's branch 1 and the card playbook's branch 1. If `HKLM:\Software\Microsoft\Office\*\Excel\InstallRoot` is **present** and `excel.exe` launches interactively, Excel IS installed → registration corruption (this playbook, branch 1). If there's no install at all → that's [`./excel-application-card-failures.md`](./excel-application-card-failures.md) branch 1, not this one.
+- **Recent Office change** — was Office upgraded, repaired, or had a second version installed shortly before the failures started? "Worked last week, broke after the M365 rollout" is the branch 1 fingerprint.
+- **Host process list at failure time** — `Get-Process EXCEL` / `tasklist /FI "IMAGENAME eq EXCEL.EXE"` on the host. A lingering `EXCEL.EXE` (especially one owned by the Robot's session with no visible window) is the branch 2 signal. Distinguish an **orphan** (no UI, Robot-session-owned, left by a prior job) from a **user-owned** instance (interactive UI, logged-in user's session).
+- **Loaded COM add-ins** — `HKLM:\Software\Microsoft\Office\Excel\Addins\` and `HKCU:\Software\Microsoft\Office\Excel\Addins\` enumerate registered add-ins and their `LoadBehavior`. `UiPath.Integration.ExcelAddin` with `LoadBehavior=3` on a runtime host is the branch 3 signal.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, the inner HRESULT, and the surface.** From `uip or jobs get <job-key> --output json` → `Info`: the `BusinessException` / `InvalidCastException` message, the **inner exception HRESULT**, and the full stack. From workflow source: confirm the scope is the Classic `<uix:ExcelApplicationScope>` element (NOT `<uix:UseExcelFile>`) and that there's a SINGLE scope (multiple scopes racing → card playbook branch 3, not here). From `project.json`: the `UiPath.Excel.Activities` version. From job logs: any Trace lines naming the host's Excel state or the acquisition step.
+
+2. **Branch the diagnostic on the signature.**
+   - `BusinessException: Make sure Excel is installed.` + inner `TYPE_E_LIBNOTREGISTERED` (`0x8002801D`) or `REGDB_E_CLASSNOTREG` (`0x80040154`) → could be this playbook's branch 1 (registration broken) OR the card playbook's branch 1 (Excel truly absent). Disambiguate at step 3.
+   - `BusinessException: Failed opening the Excel file. ... already used by another process` → branch 2; go to step 4.
+   - `InvalidCastException` on `System.__ComObject` + `E_NOINTERFACE` (`0x80004002`) → branch 3; go to step 5.
+
+3. **Disambiguate branch 1 (registration corruption) from "Excel truly not installed."** This is the decisive fork:
+   - **Is Excel installed on the host?** Check `Get-ItemProperty 'HKLM:\Software\Microsoft\Office\*\Excel\InstallRoot'` (PowerShell) and whether `excel.exe` exists under `C:\Program Files\Microsoft Office\root\Office16\` (or equivalent). **No install at all → STOP: this is [`./excel-application-card-failures.md`](./excel-application-card-failures.md) branch 1**, not registration corruption.
+   - **Does Excel launch interactively?** Have the host operator open Excel from the Start menu. If it opens cleanly, the binary is fine and the problem is COM **activation** registration, not the install — branch 1 (this playbook) confirmed.
+   - **Was Office recently changed?** Check for a recent upgrade (M365 / Office 2024 click-to-run), a second Office version, or an interrupted update / repair. A version change immediately before the failures is the branch 1 fingerprint.
+   - **Is the inner HRESULT `TYPE_E_LIBNOTREGISTERED` (`0x8002801D`)?** That HRESULT specifically means the type library isn't registered — strong evidence of stale / orphaned `TypeLib` keys from a previous Office build, i.e., registration corruption rather than a missing install.
+
+4. **Confirm branch 2 (workbook held by another EXCEL.EXE).** Check:
+   - **Host process snapshot at failure time** — `Get-Process EXCEL` on the host. A lingering `EXCEL.EXE` confirms the lock holder exists. (The timestamp matters — the locking process may be gone by the time you check; correlate with the job's run time.)
+   - **Orphan vs. user-owned** — an orphan has no visible window and is owned by the Robot's session (left by a prior crashed / force-killed job). A user-owned instance has an interactive UI in a logged-in user's session. `Get-Process EXCEL | Select-Object Id, SI, MainWindowTitle` (the `SI` session id and empty `MainWindowTitle` flag an orphan).
+   - **File handle** — if Sysinternals is available, `handle.exe -a "<workbook-path>"` names the exact process holding the file.
+   - **Prior-job correlation** — check the Robot's `Execution.log` (`%LocalAppData%\UiPath\Logs\Execution.log`) for a prior job on the same host that opened this workbook and ended abnormally (faulted / killed) without a clean scope-close. That prior job is the orphan's origin.
+
+5. **Confirm branch 3 (COM Add-in interface clash).** Check:
+   - **Inner HRESULT** — `0x80004002 E_NOINTERFACE` inside an `InvalidCastException` on `System.__ComObject` is the fingerprint. The message names the interop interface it failed to cast to (`Microsoft.Office.Interop.Excel.Application` / `Workbook` / `Worksheet`).
+   - **Registered Excel COM add-ins** — enumerate `HKLM:\Software\Microsoft\Office\Excel\Addins\` and `HKCU:\Software\Microsoft\Office\Excel\Addins\`. Look for `UiPath.Integration.ExcelAddin` (the Studio Excel Add-in, meant for design-time recording — not for runtime hosts) or any third-party add-in with `LoadBehavior=3` (load at startup).
+   - **Reproduce by isolating add-ins** — launch Excel on the host with `excel.exe /safe` (add-ins disabled). If a manual COM open then succeeds where the scope failed, an add-in is the culprit.
+
+The root cause is **which of the three COM-interop surfaces** the failure maps to: broken interop registration on an installed Excel (branch 1), the workbook held by another `EXCEL.EXE` (branch 2), or a COM add-in corrupting the interop interface (branch 3). A confirmed finding names the surface plus its decisive evidence — the inner HRESULT, the host's install-vs-registration state, the lock-holding process, or the offending add-in.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — COM registration corruption (Excel present, interop broken):**
+  - **Office Online Repair (canonical fix):** Windows Settings → Apps → Installed Apps → Microsoft Office → Modify → **Online Repair**. This re-registers the Excel COM classes and type libraries from the current build and clears stale registration from the prior version. Requires admin rights on the Robot host. This is the right first move when the breakage followed an Office upgrade.
+  - **UiPath "Repair Tool for Microsoft Office":** UiPath Studio → Tools → "Repair Tool for Microsoft Office". Lighter than Online Repair; re-registers the Excel interop components without a full Office repair. Quick to try first if you don't have admin rights for Online Repair.
+  - **Targeted `TypeLib` cleanup (only if the error is `TYPE_E_LIBNOTREGISTERED` and repair didn't resolve it):** stale `TypeLib` keys from a previous Office build can survive a repair. **Back up the registry key before editing.** In `regedit`, under `HKCR\TypeLib\`, the Excel type library GUID is `{00020813-0000-0000-C000-000000000046}`; ensure its version subkeys point to the **currently installed** Office version's `excel.exe` / `EXCEL.EXE` typelib path and remove orphaned version subkeys that reference an uninstalled build. Editing the registry is the last resort — prefer Online Repair, which does this safely and completely.
+  - **Cross-branch alternative — drop COM entirely:** if the workflow doesn't actually need Excel COM features (formula recalc, macros, formatting interaction), migrate off the Classic scope to Workbook activities or a Modern OpenXML `Use Excel File` card. See [`./excel-application-card-failures.md`](./excel-application-card-failures.md) branch 1 resolution for the migration steps. This sidesteps the whole COM-registration surface.
+
+- **Branch 2 — Workbook held by another EXCEL.EXE:**
+  - **Clear orphan processes as a recovery step:** add a `Kill Process` activity with `ProcessName = "EXCEL"` immediately BEFORE the `Excel Application Scope` to terminate stray headless instances. **Caveat:** this is a blunt instrument — it also kills any Excel the interactive user has open. Use it only on dedicated unattended Robot hosts where no human is working in Excel, never on attended / shared machines.
+  - **Fix the root cause of orphans (preferred):** orphans come from scopes that didn't close cleanly. Ensure the failing/aborting upstream workflow closes its Excel scope properly (don't `Application.Quit` from a child macro — see [`./execute-macro-failures.md`](./execute-macro-failures.md) branch 3); wrap multi-scope workflows in an `Excel Process Scope` so EXCEL.EXE lifecycle is governed; avoid force-killing jobs mid-scope.
+  - **User-owned lock:** if the holder is an interactive user's Excel instance, the file simply can't be opened exclusively while it's in use. Coordinate so the workbook isn't manually open during automation runs, point the automation at a copy, or open read-only (`ReadOnly = True` on the scope) if the workflow only reads.
+  - **Network-share lock:** if the workbook is on a UNC share, the lock may be held by a different host. The lock owner (`.~lock` / owner file, or `handle.exe` on the holding host) names it; resolve at the share level.
+
+- **Branch 3 — COM Add-in interface clash:**
+  - **Disable the offending COM add-in (canonical fix):** open Excel manually on the host → File → Options → Add-ins → at the bottom set the **Manage** dropdown to **COM Add-ins** → **Go** → uncheck `UiPath.Integration.ExcelAddin` (and any suspect third-party add-in) → OK. Restart the automation. The Studio Excel Add-in is a design-time recording aid; it should not be loaded on a runtime Robot host.
+  - **Disable per-machine via registry (for unattended provisioning):** set `LoadBehavior` to `0` under the add-in's key in `HKLM:\Software\Microsoft\Office\Excel\Addins\UiPath.Integration.ExcelAddin` (and the `HKCU` hive for the Robot user). This prevents the add-in from loading at Excel startup across jobs without manual UI steps — bake it into the host-provisioning runbook.
+  - **Confirm with `/safe`:** validate the fix by launching `excel.exe /safe` and confirming a manual COM open succeeds; then re-run the job with the add-in disabled.
+  - **Third-party add-in that's required:** if the clashing add-in genuinely must stay loaded, isolate Excel automation to a host without it, or move the workflow to the Workbook surface (no `EXCEL.EXE`, so no add-in loads at all).
+
+## Anti-patterns (what NOT to do)
+
+Common advice for Classic Excel Application Scope COM failures contains workarounds that mask the fault. The agent should NOT recommend any of these as a primary resolution.
+
+- **"Add a `Delay` before the Excel Application Scope."** A Delay does nothing for a broken COM registration (branch 1) or an add-in clash (branch 3) — the registry state and loaded add-ins are identical a few seconds later. For an orphan-process lock (branch 2) a Delay only "helps" if the orphan happens to exit during the window, which is non-deterministic. Fix the registration, clear the orphan deterministically, or disable the add-in instead.
+
+- **"Wrap the scope in a bare `Try Catch` and continue on error."** Catching `BusinessException` / `InvalidCastException` and only logging turns the failure into a silent skip — the child activities don't run and the workflow proceeds with missing data. All three branches here are deterministic configuration / environment faults; suppressing them hides a host that will fail every run. Use Try-Catch only with a real recovery path (kill orphan + retry, notify ops, fall back to Workbook activities).
+
+- **"Reinstall Office from scratch to fix the registration error."** For branch 1, a full uninstall/reinstall is disproportionate and slow. **Online Repair** re-registers the COM classes and type libraries without the downtime and license-reactivation churn of a reinstall. Reserve a full reinstall for cases where repair demonstrably fails.
+
+- **"`Kill Process EXCEL` unconditionally at the start of every workflow."** On a shared / attended host this destroys the interactive user's open workbooks (data loss). It's a valid recovery ONLY on dedicated unattended hosts. Even there, prefer fixing what leaves orphans (clean scope close, no macro `Application.Quit`, `Excel Process Scope` for multi-scope flows) over routinely killing processes.
+
+- **"Set `Visible: True` to see what's happening."** On unattended hosts the desktop session often isn't rendered, so the property has no diagnostic value, and it adds COM-UI overhead. It doesn't surface registration corruption, locks, or add-in clashes — use the host's process list, registry, and `excel.exe /safe` instead.
+
+## Prevention (cross-branch)
+
+- **Pin the Office build on Robot hosts** and route Office upgrades through a change process that includes an Excel-COM smoke test (a workflow that opens and reads a workbook via Classic scope) after every Office update. This catches branch 1 registration breakage before production jobs hit it.
+- **Strip the Studio Excel Add-in from runtime hosts.** `UiPath.Integration.ExcelAddin` is a design-time tool; set its `LoadBehavior=0` (or don't install it) on unattended Robot hosts to prevent branch 3 clashes. Document this in the host-provisioning runbook.
+- **Govern EXCEL.EXE lifecycle** to prevent orphans (branch 2): wrap multi-scope workflows in an `Excel Process Scope`, never tear down Excel from a child macro (`Application.Quit` / `Workbooks.Close`), and avoid force-killing jobs while a scope is open.
+- **Prefer the lowest-COM surface that meets the requirement.** If a workflow doesn't need Excel COM features, use Workbook activities or a Modern OpenXML `Use Excel File` card — that eliminates the entire COM-interop failure surface (all three branches here) on hosts that don't otherwise need Excel.
+- **For attended / shared hosts,** never bake an unconditional `Kill Process EXCEL` into workflows; coordinate workbook access so automation and humans don't contend for the same file.
+
+## Related
+
+- [`./excel-application-card-failures.md`](./excel-application-card-failures.md) — the SHARED scope-container playbook. Excel **truly not installed** (branch 1 there), empty / illegal `WorkbookPath` (branch 2), COM/RPC **races across multiple scopes** (branch 3), **child activity outside any scope** (branch 4), and **sensitivity-label** rejection (branch 5) all live there. This playbook is the Classic-COM-interop complement: a single installed-but-broken / contended / hijacked COM layer.
+- [`./execute-macro-failures.md`](./execute-macro-failures.md) — branch 3 there (macro tears down Excel via `Application.Quit` / `Workbooks.Close`) is a common upstream cause of the orphan / disconnected-process state that this playbook's branch 2 observes downstream.
+- [`../overview.md`](../overview.md) — package overview; the OpenXML-vs-COM provider model and the Classic-scope-is-COM-only distinction are load-bearing for all three branches here.
+- [`../summary.md`](../summary.md) — navigation across all Excel Activities playbooks.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/execute-macro-failures.md

@@ -0,0 +1,149 @@
+---
+confidence: medium
+---
+
+# Execute Macro / Run Spreadsheet Macro Failures
+
+## Context
+
+A `UiPath.Excel.Activities` Execute Macro activity (classic `ExecuteMacro`, or modern `Run Spreadsheet Macro` under `Use Excel File`) runs a VBA macro inside the open workbook. The activity bridges UiPath's managed runtime to Excel via COM; failures can originate in the macro's VBA code, in Excel's COM dispatch, in the Robot host's Excel configuration, or in the bridge between the two.
+
+What this looks like — most failures surface as `System.Runtime.InteropServices.COMException`, often with one of these HRESULTs / messages:
+
+- `0x80020009 (DISP_E_EXCEPTION)` — "Exception occurred." The macro itself threw a VBA error via `IDispatch`. The inner VBA error (Object required, Subscript out of range, Type mismatch, Application-defined or object-defined error) is the load-bearing detail.
+- `0x800A03EC` — generic Excel error during macro execution.
+- `0x800AC472` — apartment-threading violation from concurrent COM access.
+- `Cannot run the macro '<name>'. The macro may not be available in this workbook or all macros may be disabled.` — Excel's own error message wrapped in a COMException.
+
+Failures may also surface as:
+- Job hangs with no exception — Excel modal dialog (`MsgBox`, `InputBox`, VBA `Stop` / `Debug.Print` break, "End/Continue" recovery dialog) waiting for a user response that the Robot's unattended session cannot provide.
+- `UiPath.Excel.BusinessException` — Excel COM rejected the macro call before it ran.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Macro name not found in the workbook** — configured `Macro` property is a name (`MyModule.RunImport` or `RunImport`) that does not exist in any code module of the open workbook. Symptom: COMException with message `Cannot run the macro '<name>'. The macro may not be available in this workbook or all macros may be disabled.` Causes: typo, macro renamed upstream, macro lives in a different workbook / add-in, module-qualifier mismatch.
+2. **VBA error inside the macro (DISP_E_EXCEPTION)** — the macro ran but its VBA code threw. The activity sees the COM `DISP_E_EXCEPTION` wrapper but the inner detail is the VBA error: `Run-time error '91': Object variable or With block variable not set`, `Run-time error '9': Subscript out of range`, `Run-time error '13': Type mismatch`, `Run-time error '1004': Application-defined or object-defined error`, etc. Causes: bug in the macro itself, assumption about workbook contents that doesn't hold at runtime, dependency on a worksheet / range / named cell that isn't there.
+3. **Macro tears down the Excel instance** — the VBA code calls `Workbooks.Close`, `ActiveWorkbook.Close`, `Application.Quit`, `ThisWorkbook.Close`, or similar. The UiPath Excel Application Scope (or `Use Excel File` with COM) owns the Excel instance; when the macro shuts it down, the next activity finds the COM object gone. Symptom: COMException with HRESULT like `0x80010108 (RPC_E_DISCONNECTED)` on the NEXT activity, not necessarily the macro itself. Macro may have logged "succeeded" before tearing down.
+4. **Modal dialog from macro** — the VBA code displays `MsgBox`, `InputBox`, or a custom `UserForm`, OR Excel's own dialog (e.g., "There is already data in [cell]. Do you want to replace it?" from a write that conflicts) interrupts execution. Symptom: job hangs indefinitely; no exception; the Robot eventually times out (turn timeout, `UIPATH_SESSION_TIMEOUT`, or operator manual kill). Excel COM cannot respond while a modal dialog is open.
+5. **Macros disabled by Trust Center policy on the Robot host** — Excel's Trust Center on the Robot user's profile has `Disable all macros without notification` (or `Disable VBA macros except digitally signed`) and the workbook's macros are not in a trusted location or signed by a trusted publisher. Symptom: COMException `Cannot run the macro '<name>'. The macro may not be available in this workbook or all macros may be disabled.` Same error string as branch 1, but the macro DOES exist in the workbook. Distinguish by: macro name confirmed present + workbook works on developer's host (interactive Excel where Trust Center has dev defaults) → branch 5; macro name absent in workbook → branch 1.
+6. **Concurrent COM access (apartment violation)** — Excel COM is single-threaded apartment (STA). When multiple parallel activities (or a separate automation, e.g., another Robot job on the same host) call into the Excel COM apartment, the second caller hits `0x800AC472` or `RPC_E_SERVERCALL_RETRYLATER`. Symptom: COMException with one of those HRESULTs; intermittent (only when the parallel call lands during macro execution); fails more on multi-Robot hosts.
+7. **Macro depends on missing add-in or ActiveX control** — the VBA code references an add-in (`Tools → References` in the VBE) or ActiveX control that is registered on the developer's machine but NOT on the Robot host (or registered under a different user profile than the Robot's). Symptom: VBA error `Run-time error '424': Object required` or `Compile error: Can't find project or library`; surfaces as `DISP_E_EXCEPTION` like branch 2 but the inner is a missing-reference error rather than a logic bug.
+
+What to look for:
+- **The exact COMException HRESULT / message** — the strongest first signal. `0x80020009 DISP_E_EXCEPTION` → branch 2 or 7. `Cannot run the macro '<name>'...` → branch 1 or 5. `RPC_E_DISCONNECTED` on a subsequent activity → branch 3. `0x800AC472` → branch 6. Job hangs / no exception → branch 4.
+- **The inner VBA error message** if visible in the exception's `Message` or in the activity's Trace logs. UiPath usually captures the macro's `Err.Description` in the COMException wrapper.
+- **Workflow source** — confirm the configured `Macro` name (literal vs. expression), whether the scope is `Excel Application Scope` (classic, COM-only) or `Use Excel File` with COM-forcing properties, and whether parallel activities access Excel.
+- **Robot host's Excel configuration** — Trust Center settings (`File → Options → Trust Center → Trust Center Settings → Macro Settings`), Trusted Locations, installed add-ins under the Robot user.
+- **Workbook contents** — does the macro name exist in the workbook's VBA code? Macros in `Personal.xlsb` are NOT in the open workbook; they're in a separate workbook loaded on Excel startup. Robots usually don't load `Personal.xlsb`.
+- **Run pattern** — every run fails → persistent (branches 1, 3, 5, 7). Intermittent → branch 6 (concurrent) or branch 4 (modal dialog only on certain inputs).
+
+## Investigation
+
+1. **Capture the exact error.** From `or jobs get <job-key> --output json`: the exception class, full message, HRESULT (if a COMException), and any inner exception or VBA error text the activity surfaced. From workflow source: the activity, configured `Macro` name (literal or expression), and the scope.
+
+2. **Categorize the symptom.**
+   - Job has an exception → continue to step 3.
+   - Job hangs / times out with no exception → **branch 4** (modal dialog). Confirm: the macro is known to display a dialog under certain inputs, or Excel surfaced a dialog (data-overwrite warning, recovery dialog, end/continue debug prompt). Skip to Resolution.
+
+3. **Match the HRESULT / error message to a branch.**
+   - `Cannot run the macro '<name>'. The macro may not be available in this workbook or all macros may be disabled.` → branches 1 or 5; go to step 4.
+   - `0x80020009 (DISP_E_EXCEPTION)` → branches 2 or 7; go to step 5.
+   - `0x80010108 (RPC_E_DISCONNECTED)` on the NEXT activity after the macro → branch 3; go to step 6.
+   - `0x800AC472` / `RPC_E_SERVERCALL_RETRYLATER` → branch 6; go to step 7.
+   - Other HRESULT → check Microsoft's HRESULT documentation; default to inspecting the workbook source.
+
+4. **Distinguish branches 1 vs. 5 (macro-not-found vs. macros-disabled).** Ask the user to verify:
+   - **Open the workbook in Excel** (on any host) → `Alt+F11` (VBA editor). Confirm the configured macro name exists in a code module. If absent → **branch 1** (name mismatch, typo, or macro in a different scope). If present → continue.
+   - **On the Robot host, under the Robot user's profile**: open Excel → `File → Options → Trust Center → Trust Center Settings → Macro Settings`. If set to `Disable all macros without notification` or `Disable all macros with notification` (and the workbook is not in a trusted location / signed) → **branch 5** (macros disabled).
+   - The user's own dev workstation having a permissive Trust Center setting is the canonical "works on dev / fails on Robot" pattern for branch 5.
+
+5. **Distinguish branches 2 vs. 7 (VBA bug vs. missing dependency).** Look at the inner VBA error text from the COMException:
+   - `Run-time error '91': Object variable or With block variable not set` — usually branch 2 (logic bug).
+   - `Run-time error '9': Subscript out of range` — usually branch 2 (worksheet / range assumption).
+   - `Run-time error '13': Type mismatch` — usually branch 2.
+   - `Run-time error '1004': Application-defined or object-defined error` — could be either; ambiguous. Check what the macro was doing at the time.
+   - `Run-time error '424': Object required` or `Compile error: Can't find project or library` — **branch 7** (missing reference / add-in / ActiveX).
+   - `Run-time error '429': ActiveX component can't create object` — **branch 7** (control not registered under Robot user).
+
+6. **Confirm branch 3 (macro tears down Excel).** Inspect the VBA source. Search for `Close`, `Quit`, `ThisWorkbook.Close`, `ActiveWorkbook.Close`, `Application.Quit`. The macro must not call any of these — UiPath owns the Excel lifecycle. If found, branch 3 is confirmed.
+
+7. **Confirm branch 6 (concurrent COM access).** Look for:
+   - The workflow uses `Parallel` activities containing Excel calls.
+   - Multiple Robot jobs against the same workflow on the same host (`uip or jobs list --process-name '<process>' --host '<MOCK-HOST>'`) overlap with the macro window.
+   - A different automation on the same host using Excel (PowerShell, another RPA tool, scheduled VBA add-in).
+   - Failures are intermittent — the symptom of an STA race.
+
+The root cause must name the specific HRESULT / VBA error / Trust Center setting / VBA call / concurrency pattern responsible. A generic "the macro failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Macro name not found:**
+  - Open the workbook in Excel and confirm the macro's actual qualified name (module name + sub name: `Module1.RunImport`). Update the activity's `Macro` property to match verbatim.
+  - If the macro lives in a separate workbook / add-in, change the workflow to either open that source (Excel Application Scope on the source file, then run macro), or move the macro into the target workbook.
+  - `Personal.xlsb` macros are not available to Robot sessions by default (the Robot user's Excel does not auto-load `Personal.xlsb`). Move the macro into the project workbook or into a workbook the workflow explicitly opens.
+  - Prevention: name macros with explicit module qualifiers (`Module1.RunImport`, not `RunImport`); document the macro contract between workbook publisher and workflow consumer.
+
+- **Branch 2 — VBA error inside the macro:**
+  - Open the workbook in Excel, `Alt+F11` to the VBE, and reproduce the macro under the same inputs. The VBE will break at the offending line.
+  - Fix the VBA logic. Common patterns: null-safe object references (`If Not rng Is Nothing Then`), explicit sheet qualifiers (`ThisWorkbook.Sheets("Data").Range("A1")` rather than `Range("A1")`), defensive type checking before assignment.
+  - For long-running macros, add structured error handling in VBA: `On Error GoTo ErrHandler` + `Err.Raise` with a clear description, so the COMException surfaces a useful message rather than a generic DISP_E_EXCEPTION.
+  - Prevention: unit-test macros on the same data shapes the workflow will produce. Do not rely on workbook state assumptions that the workflow's earlier activities could violate.
+
+- **Branch 3 — Macro tears down Excel:**
+  - Remove `Workbooks.Close`, `ActiveWorkbook.Close`, `Application.Quit`, `ThisWorkbook.Close` from the VBA. UiPath owns the Excel lifecycle when the macro runs inside Excel Application Scope or `Use Excel File`.
+  - If the macro genuinely needs to dismiss the workbook (e.g., it opened a different workbook for processing), have it close ONLY workbooks it opened itself, never `ThisWorkbook` or `ActiveWorkbook` when those are the host workbook.
+  - Prevention: workbook publisher and workflow author should agree on a contract — macros run inside UiPath's scope must not modify the application lifecycle. Add a code-review checklist for VBA macros that will be invoked from UiPath.
+
+- **Branch 4 — Modal dialog from macro:**
+  - Remove `MsgBox`, `InputBox`, and `UserForm.Show` calls from the macro. Replace with logging to a worksheet, an `Err.Raise` with a descriptive message, or a status output range the workflow reads after the macro finishes.
+  - For Excel's own dialogs (data-overwrite warnings, save-as prompts), set `Application.DisplayAlerts = False` at the start of the macro (and `True` at the end). Note this suppresses ALL Excel dialogs during the macro, including legitimate confirmation prompts — use deliberately.
+  - For VBA debug interruptions (`Stop`, `Debug.Print` with breakpoints): remove all `Stop` statements and clear all breakpoints before saving the workbook for production.
+  - Prevention: ban interactive UI calls in VBA macros that run under UiPath. Macros are headless; they must not require user input.
+
+- **Branch 5 — Macros disabled by Trust Center:**
+  - **Preferred:** add the workbook's containing folder to Excel's Trusted Locations under the Robot user's profile. Open Excel as the Robot user → `File → Options → Trust Center → Trust Center Settings → Trusted Locations → Add new location`. Persistent under that user.
+  - Alternative: sign the macro with a code-signing certificate that's trusted on the Robot host, and set Trust Center to `Disable VBA macros except digitally signed macros`.
+  - Last resort (security-relaxed): set `Enable VBA macros` (the most permissive option) on the Robot user's Excel. Acceptable only when the Robot host is dedicated to trusted automation and not used for general Office work.
+  - Prevention: when provisioning Robot hosts, configure Excel's Trusted Locations as part of host setup. Document the location list in the host build runbook.
+
+- **Branch 6 — Concurrent COM access:**
+  - Serialize Excel access. Options:
+    - Remove `Parallel` activities that touch Excel; run those branches sequentially.
+    - If multiple Robot jobs on the same host need Excel, serialize via a per-host lock asset OR a single-performer queue on the workflow.
+    - If another automation on the host uses Excel, separate them (different hosts, or coordinated schedules).
+  - For unavoidable intermittent races, add a Retry Scope around Execute Macro with exponential back-off (3 attempts, 5s / 15s / 30s). Excel COM apartment violations are usually transient — a short wait often unblocks them.
+  - Prevention: do not design workflows that parallel-call into Excel COM. Single-threaded apartment is a hard constraint, not a quirk.
+
+- **Branch 7 — Missing add-in or ActiveX control:**
+  - Identify the missing reference: open the workbook in Excel on the Robot host (under the Robot user) → `Alt+F11` → `Tools → References`. Any reference marked "MISSING:" is the culprit.
+  - Install / register the add-in or control on the Robot host under the Robot user's profile. Add-ins: copy the `.xlam` / `.xla` to `%AppData%\Microsoft\AddIns\` and enable in Excel's Add-ins dialog. ActiveX: `regsvr32 <control.dll>` as admin, but verify the control is licensed for unattended use.
+  - Alternative: rewrite the macro to not depend on the missing reference (early binding → late binding via `CreateObject`, OR remove the dependency entirely if possible).
+  - Prevention: document every external dependency the workbook's macros require. Provision Robot hosts with that dependency list; verify with a smoke-test workflow that exercises each macro.
+
+## Anti-patterns (what NOT to do)
+
+Common advice for ExecuteMacro failures contains workarounds that hide bugs rather than fix them. The agent should NOT recommend either as a primary resolution.
+
+- **"Add a `Delay` activity before Execute Macro."** A `Delay` is a workaround for a race condition or initialization issue that the workflow author has not actually diagnosed. It "works" intermittently and hides the underlying bug — usually branch 3 (Excel torn down by a previous macro), branch 6 (concurrent COM access), or genuine workbook write-flush latency. A reliable fix names the specific timing dependency and addresses it (sequence activities correctly, use `DoEvents` in VBA before returning, configure `Application.CalculateUntilAsyncQueriesDone = True` for power-query workbooks). If a `Delay` is genuinely required, treat it as a diagnosis hint about an underlying timing problem, document the dependency in a comment, and pick a duration that's an order of magnitude above the worst observed case rather than the minimum that "works."
+
+- **"Wrap Execute Macro in a Try Catch and continue on error."** A bare Try-Catch that catches `COMException` (or `System.Exception`) and only logs without re-throwing turns macro failures into silent skips — the workflow proceeds as if the macro succeeded, producing wrong outputs, missing data, and downstream failures that are much harder to diagnose than the original COMException. Use Try-Catch only with a real recovery path: fall back to a different macro, mark a queue item Failed with the COMException message, send a notification, or re-throw a domain-specific exception.
+
+## Prevention (cross-branch)
+
+- Workbook authors must treat macros invoked from UiPath as headless: no `MsgBox`, no `InputBox`, no `UserForm`, no `Stop` / debug breakpoints. Failures surface via `Err.Raise` or a status range, not via UI.
+- Macros must not change Excel's application lifecycle (no `Workbooks.Close` / `Application.Quit` / etc.). UiPath owns it.
+- VBA must use explicit qualifiers (`ThisWorkbook.Sheets("Data").Range("A1")`) not implicit `ActiveSheet` / `Selection`. The Robot's session may not have the same active context as the developer's interactive Excel.
+- Robot hosts should be provisioned with: Excel's Trusted Locations covering the automation data folder; the same add-ins as the developer's machine; the same ActiveX controls registered under the Robot user; the Trust Center macro setting compatible with the workbook's signing posture.
+- Workflow authors should:
+  - Validate the configured `Macro` name against the workbook before invocation (a smoke-test enumerator that lists VBA macros, similar to `Get Workbook Sheets` for sheets).
+  - Never use `Delay` to paper over Excel timing issues.
+  - Never use bare `Try Catch` around Excel activities; always pair Catch with a real recovery action.
+  - Serialize Excel access — no `Parallel` activities touching Excel, single-performer queues for cross-job concerns.
+
+## Related
+
+- Other Excel Activities failure fingerprints (read-side failures) are separate playbooks — see [`../summary.md`](../summary.md).
+- The "Try-Catch suppression around Excel scopes" anti-pattern is consistent across all Excel playbooks; reinforcing it here.
+- For headless Excel automation that does NOT need VBA macros, consider migrating the macro logic into UiPath activities or the cloud surface (`o365-activities/overview.md`). Macros are a portability hazard between developer and Robot environments; native UiPath logic is more deterministic.

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

@@ -0,0 +1,145 @@
+---
+confidence: medium
+---
+
+# Write Range Failures
+
+## Context
+
+A `UiPath.Excel.Activities` `Write Range` activity (Classic `WriteRange` inside `Excel Application Scope` / standalone Workbook surface, or Modern `WriteRangeX` inside `Use Excel File`) writes a `DataTable` to a worksheet starting at a configured cell. Failures originate at one of five surfaces: source-table integrity (the `DataTable` variable is null), file acquisition (workbook locked / read-only), source-shape edge cases (header-only DataTable with `ExcludeHeaders=False`), target-sheet structure (hidden rows / columns inside the write boundary as of package v2.8.5+), or data volume / content (oversized batches, formula-prefix characters interpreted as broken formulas).
+
+What this looks like — Write Range faults surface as one of these signatures:
+
+- `System.NullReferenceException: Object reference not set to an instance of an object` — the configured `DataTable` argument is `Nothing` / `null`. Branch 1.
+- `System.IO.IOException: The process cannot access the file '<path>' because it is being used by another process.` — file held by another process or by a stale UiPath scope. Branch 2.
+- `UiPath.Excel.BusinessException` (wording varies — typically "The Excel Activity option 'Ignore empty source' is ineffective" or "Failing on Empty Header") — the source `DataTable` has 0 rows AND `ExcludeHeaders` is False. Branch 3.
+- Explicit error (package v2.8.5+) referencing hidden rows / columns within the target write region — `UiPath.Excel.BusinessException` mentioning "hidden rows or columns" or similar. Branch 4.
+- `System.OutOfMemoryException`, `System.Runtime.InteropServices.COMException`, or `UiPath.Excel.BusinessException: The data you want to write has a wrong format, or Excel is busy.` — branch 5 (oversized batches or formula-prefix data).
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Uninitialized / null DataTable** — the source `DataTable` variable passed to the activity is `Nothing`. Causes: variable declared but never assigned (missing `Build Data Table` / `Read Range` step earlier); preceding `Read Range` ran against a missing sheet and returned `Nothing` instead of an empty DataTable; conditional branch skipped the assignment; variable name typo so the activity reads the wrong scope's variable. Symptom is the canonical NRE on the activity, NOT inside Excel — the activity throws before any COM / OpenXML call.
+2. **Workbook locked or opened read-only** — same fault family as the read-range / delete-range / write-cell file-locked surface: a different process holds the file (user-opened Excel UI, orphan `EXCEL.EXE` from a prior job, AV scanner, a different host's lock on a network share), OR the file is read-only at the OS layer (NTFS ACL, `Mark as Final`, Protected View on a downloaded copy, Modern `Use Excel File` scope with `ReadOnly=True`).
+3. **Empty source DataTable + `ExcludeHeaders=False`** — the source DataTable has 0 rows (only column definitions, no data). With `ExcludeHeaders=False` (default), the activity tries to write the header row + 0 data rows; some surfaces / package versions surface this as a BusinessException rather than a no-op. The note in the activity's documentation that "`Ignore empty source` excludes the empty case" is misleading — `Ignore empty source` only applies when the DataTable variable itself is `Nothing`, not when it's an initialized table with 0 rows. Workflow authors hit this when a preceding `Filter DataTable` removed every row, leaving the schema but no content.
+4. **Hidden rows / columns in the target write range (package v2.8.5+)** — the workbook's target sheet has rows or columns hidden inside the rectangle the `DataTable` would write into (manual hide, AutoFilter, or grouping). Pre-2.8.5 versions silently wrote into the hidden cells and the user saw "missing" data; 2.8.5+ throws an explicit `BusinessException` flagging the hidden ranges so the workflow author catches the data-loss risk before it ships. Common trigger: a sheet shared with a human user who applied a filter before the job ran.
+5. **Out-of-memory / COM exceptions on volume or formula-prefix data** — two distinct sub-causes that share signatures:
+   - **Oversized batches**: writing a multi-hundred-thousand-row `DataTable` in one call exhausts Excel COM's per-call buffer (or .NET managed memory under heavy COM marshaling). Surfaces as `OutOfMemoryException` or `COMException` with a generic Excel HRESULT (`0x800A03EC`, `0x8001010A`).
+   - **Formula-prefix data**: cell values starting with `=`, `+`, `-`, or `@` are interpreted by Excel as formulas. When the literal text isn't a valid formula (e.g., `=Smith, John` for a name with a leading equals), Excel rejects the cell with `Application-defined or object-defined error`. Same signature as the volume case, different root.
+
+What to look for:
+
+- **The exception class and message** — first signal. `NullReferenceException` → branch 1. `IOException` / "cannot access the file" → branch 2. `BusinessException` mentioning "empty source" / "Ignore empty source" / "header" → branch 3. `BusinessException` mentioning "hidden rows" / "hidden columns" → branch 4. `OutOfMemoryException` or `COMException` with a generic Excel HRESULT → branch 5 (large or formula-prefix).
+- **Workflow source** — which `Write Range` surface (Classic Workbook / Classic scope / Modern), the configured `DataTable` argument (literal variable name vs. an expression), the configured `SheetName` / `Range` / `ExcludeHeaders` / `AddHeaders`, and the parent container (`Excel Application Scope`, `Use Excel File`, or unwrapped Classic Workbook).
+- **The DataTable's source** — what activity produced the `DataTable` variable (`Build Data Table`, `Read Range`, `Generate Data Table from Text`, `Filter Data Table`, a coded assignment, etc.). Branch 1 traces back to whichever step was expected to populate it.
+- **Package version** — `UiPath.Excel.Activities` version from `project.json`. The hidden-rows behavior (branch 4) is version-dependent: pre-2.8.5 silently writes; 2.8.5+ throws.
+- **Target sheet state** — visible AutoFilter (funnel icons on header row), manually hidden rows / columns, grouped rows / columns collapsed, freeze panes intersecting the write range. Relevant for branch 4.
+- **`DataTable.Rows.Count` immediately before the activity** — gives branch 1 vs. branch 3 vs. valid-but-failed distinction. A `Log Message` capturing the row count + the `DataTable.Columns.Count` is the cheapest pre-write check.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, activity, and configuration.** From `uip or jobs get <job-key> --output json` → `Info`: exception class, full message, HRESULT (if COMException), inner exception. From workflow source: the `Write Range` surface (Classic Workbook / Classic scope / Modern), the configured `DataTable` argument (variable name or expression), `SheetName`, `Range`, `ExcludeHeaders`, `AddHeaders`, and the parent container. From job logs (`uip or jobs logs <key>`): the activity's Trace lines around the failure, plus any `Log Message` lines that captured the `DataTable.Rows.Count` immediately before.
+
+2. **Branch the diagnostic on the exception signature.**
+   - `NullReferenceException` → branch 1; go to step 3.
+   - `IOException` / `COMException` with "cannot access the file" / "used by another process" / "read-only" → branch 2; pivot to the read-range file-locked playbook for the full chain (see [`../summary.md`](../summary.md) for navigation).
+   - `BusinessException` mentioning "Ignore empty source" / "empty source" / "header" → branch 3; go to step 4.
+   - `BusinessException` mentioning "hidden rows" / "hidden columns" / "hidden range" → branch 4; go to step 5.
+   - `OutOfMemoryException` or `COMException` with generic Excel HRESULT (`0x800A03EC`, `0x8001010A`) → branch 5; go to step 6.
+   - `BusinessException: The sheet with the name '<name>' does not exist` → cross-cutting sheet-name mismatch; pivot to the read-range sheet-not-found playbook (see [`../summary.md`](../summary.md)). The diagnostic is identical to the read-side version.
+   - `COMException` with "protected" / "read-only" / `0x800A03EC` near `Worksheet.Protect` → cross-cutting protected-sheet surface; pivot to the write-cell playbook's branch 5 (see [`../summary.md`](../summary.md)).
+
+3. **Confirm branch 1 (uninitialized DataTable).** Inspect the workflow source. Trace the `DataTable` argument's variable backward:
+   - Find the most recent assignment / output binding for that variable in scope. If it's an `Assign`, did the expression resolve? If it's a `Read Range` output, did that activity succeed in this run? If it's a `Build Data Table` output, is the activity actually upstream of Write Range in the execution path (not in an `Else` branch that was skipped)?
+   - Add a `Log Message Level=Info Message=$"dt rows={dt.Rows.Count}, cols={dt.Columns.Count}"` immediately before the Write Range and rerun. If the log line throws NRE itself, the variable is null. If it logs `rows=0 cols=N`, branch 1 is ruled out and the failure is branch 3.
+   - Check the variable scope: a `DataTable` declared in an inner scope (`Try` body, `If` then-branch) goes out of scope at the parent boundary; if Write Range is outside, it reads `Nothing`.
+   - Check for variable-name typos: `dtCustomers` vs. `dtCustomer` — Studio doesn't always flag a misspelled reference if a same-named variable exists in an outer scope.
+
+4. **Confirm branch 3 (empty source + ExcludeHeaders=False).** Check:
+   - The `DataTable.Rows.Count` immediately before the activity is 0.
+   - `ExcludeHeaders` is False (the default for many surfaces).
+   - The DataTable was initialized (i.e., not branch 1) — confirmed if `DataTable.Columns.Count > 0`.
+   - The preceding activity that should have populated rows actually ran and matched something. Common upstream cause: `Filter DataTable` with a predicate that matches no rows, or `Read Range` against a sheet that exists but has only a header row.
+   - If `Range` is configured as a specific cell (e.g., `"A2"`) rather than empty / `"A1"`, the activity expects to write into existing data and the empty-source branch becomes more confusing because there's no header-row context.
+
+5. **Confirm branch 4 (hidden rows / columns in target range).** Two independent checks:
+   - **Package version**: open `project.json` and read `UiPath.Excel.Activities` version. If < 2.8.5, the explicit "hidden range" error does not exist in that version — the failure cannot be branch 4 by definition; recheck the exception text against the other branches.
+   - **Target sheet state**: open the workbook in Excel before running the workflow. On the target sheet, look for: AutoFilter funnel icons on the header row (`Data → Filter` toggle); manually hidden rows (right-click row header → Unhide visible? gap in row numbers); manually hidden columns (gap in column letters); grouped rows / columns (left-margin or top-margin outline brackets); freeze panes. Any of these inside the rectangle defined by `(Range starting cell) + (DataTable shape)` triggers branch 4.
+   - Reproduce manually: open the workbook in Excel, select the same target range, try to paste any value. If Excel rejects the paste with a "selection contains hidden cells" warning, the activity's BusinessException is the API-level surface of that same rejection.
+
+6. **Confirm branch 5 (out-of-memory / COM exception).** Distinguish the two sub-causes:
+   - **Volume sub-cause**: `DataTable.Rows.Count` is in the high thousands / hundreds of thousands at the time of write. The job logs may show progressive memory pressure earlier (cache warnings, GC pauses). Surfaces more often on COM-mode Modern scope or Classic surfaces (OpenXML is more memory-efficient).
+   - **Formula-prefix sub-cause**: scan the DataTable's first column / first row of data for values starting with `=`, `+`, `-`, or `@`. Common offenders: names with a leading equals (`=Smith, John` from a copy-paste error), formulas in a column the user thought was plain text, accounting / debit values that begin with `-`, email handles starting with `@`. The activity will surface this as a `COMException` referencing "Application-defined or object-defined error" or "wrong format" — the same signature as the volume sub-cause but the cause is content, not size.
+   - To distinguish without re-running: a `Log Message Level=Info Message=$"first cell of first row: '{dt.Rows(0)(0)}'"` immediately before Write Range exposes the value. If it starts with `=`, `+`, `-`, or `@`, branch 5 formula-prefix is the cause.
+
+The root cause is **which of the five surfaces** the failure maps to. A confirmed finding names the surface (Classic / Modern), the resolved runtime state of the inputs (DataTable null vs. empty vs. populated, file-acquisition state, target sheet hidden state, data volume / first-row content), and the matching exception signature.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Uninitialized / null DataTable:**
+  - Trace the variable backward to its expected source and ensure that source actually executes. If the upstream is `Read Range`, confirm the sheet name and range resolve (rule out a silent miss). If the upstream is `Build Data Table`, ensure it sits on the execution path that reaches Write Range (not behind an `If` that the run skipped).
+  - Initialize the variable at declaration: assign `dt = New System.Data.DataTable()` (or use `Build Data Table` at workflow start) so the variable is never `Nothing` even if the populating step is skipped. Write Range against a 0-row initialized DataTable becomes branch 3, not branch 1 — handle there.
+  - Promote the variable's scope: if Write Range is at a higher scope than the assignment, move the variable declaration up to the common parent scope.
+  - Fix variable-name typos: rename for clarity if a similar name exists in an outer scope (e.g., `dtCustomersFiltered` instead of reusing `dtCustomers` across nested scopes).
+  - Prevention: prefer `Log Message Level=Info Message=$"dt rows={dt.Rows.Count}"` before every Write Range. The two extra log lines turn a silent NRE into a self-diagnosing trace.
+
+- **Branch 2 — Workbook locked or read-only:**
+  - Apply the resolution from the read-range file-locked playbook (see [`../summary.md`](../summary.md) for navigation). The write side (Write Range) and the read side share the same fault surface — the file is held by another process, the lock is at the OS layer, or the file is on a network share whose semantics differ from local disk.
+  - For workbooks marked read-only via `Mark as Final` or arriving via Protected View: open the file as the Robot user, remove the `Mark as Final` flag (`File → Info → Mark as Final`), or `Unblock-File '<path>'` to lift the Mark-of-the-Web flag that triggers Protected View.
+  - For Modern `Use Excel File` scopes: confirm `ReadOnly: False` on the scope. Default-True is a footgun on `Use Excel File` for workflows that include any Write activity.
+  - For Classic Workbook `Write Range` (no enclosing scope) ALSO running alongside a Classic `Excel Application Scope` or Modern `Use Excel File` for the same path elsewhere in the workflow: replace the bare Classic Workbook Write Range with one nested inside the existing scope. Mixing surfaces against the same file is a self-inflicted lock — the scope owns the file via its mechanism, and the standalone Workbook activity refuses to acquire it.
+
+- **Branch 3 — Empty source + `ExcludeHeaders=False`:**
+  - Wrap Write Range in an `If` activity with condition `dt.Rows.Count > 0`. In the Then branch, perform the write. In the Else branch, log a warning or no-op. This is the cleanest fix because it explicitly encodes the "nothing to write" semantics rather than relying on the activity to handle it.
+  - Set `ExcludeHeaders=True` if the workflow's intent is to write only data rows (no header in the workbook). With `ExcludeHeaders=True`, an empty DataTable is treated as a 0-row, 0-column write — usually a no-op rather than an error.
+  - For workflows that aggregate filtered batches: validate the filter result earlier in the workflow. If `Filter DataTable` is the upstream cause, log the input vs. output row counts so the empty case is observable upstream rather than at the Write Range surface.
+  - Note that `Ignore empty source` (when the activity / surface supports it) only handles the `Nothing` case (branch 1) — it does NOT handle an initialized DataTable with 0 rows. The two cases need to be handled separately, despite naming that suggests otherwise.
+
+- **Branch 4 — Hidden rows / columns in target range (v2.8.5+):**
+  - Remove hidden rows / columns from the target write region before the Write Range:
+    - **Active AutoFilter**: insert a `Remove Data Filter` (Modern) or `Filter Range` with `Action: Remove` (Classic) targeting the same sheet, immediately before Write Range. After the write, re-apply the filter if downstream consumers depend on it.
+    - **Manually hidden rows / columns**: select all rows / columns containing the write target, right-click, Unhide. For a robot-only sheet, automate this with a `Hidden = False` property write OR a pre-cleanup workflow step that calls `Worksheet.Unhide()` via COM.
+    - **Grouped rows / columns collapsed**: expand the group (`Data → Ungroup`, or `Outline → Expand`) before the write. The Robot's session sees the collapsed state as hidden.
+  - If the hidden state is intentional (e.g., a report uses hidden rows for archived records that should NOT be overwritten), restructure the target range so the write does not intersect the hidden region — write to a separate sheet or a non-overlapping range.
+  - Downgrading the package to pre-2.8.5 silences the explicit error but reintroduces the silent-data-loss bug it was added to catch. Do not downgrade as a "fix"; the error is correctly flagging a real risk.
+
+- **Branch 5 — Out-of-memory / COM exceptions:**
+  - **Volume sub-cause**: chunk the write. Replace a single `Write Range` of `N` rows with a loop that writes batches of 5,000–20,000 rows each (tune to the workbook / host). Use `Append Range` for batches after the first, or a per-batch `Write Range` with a computed starting cell `"A" + ((batchIndex * batchSize) + 2).ToString()`. The 20K-row threshold is empirical — workbooks with many columns or rich types should use smaller batches.
+  - Alternative for the volume sub-cause: switch to the OpenXML provider if you're on Classic / Modern COM. `Use Excel File` defaults to OpenXML when no COM-forcing property is set; OpenXML's memory footprint is much smaller for large data.
+  - **Formula-prefix sub-cause**: pre-clean the data before the write. Two approaches:
+    - **Escape the literal**: prepend an apostrophe (`'`) to each offending cell value via a `For Each Row` + cell update. Excel treats apostrophe-prefixed strings as literal text. The apostrophe is hidden in the rendered cell but stored.
+    - **Pre-clean by type**: if the column should be text-only (names, IDs), enforce a `String` type on the DataTable column with `Convert.ToString(...).TrimStart("="c, "+"c, "-"c, "@"c)` to strip leading formula characters. Document the transformation in the workflow so consumers know the data has been sanitized.
+  - For workflows that write user-supplied content into Excel (form input, scraped names, queue payloads): always apply the escape / pre-clean step. Do not assume input data is formula-safe.
+
+## Anti-patterns (what NOT to do)
+
+Common advice for Write Range failures contains workarounds that hide bugs rather than fix them. The agent should NOT recommend any of these as a primary resolution.
+
+- **"Add a `Delay` activity before Write Range."** A `Delay` is a workaround for a race condition or initialization issue that the workflow author has not actually diagnosed. For Write Range, the most common temptation is to add a delay before the activity to "let Excel settle" after a preceding `Use Excel File` open, or to mask branch 2 (file lock) by waiting for a stuck process to release. The Delay works intermittently — long enough for the lock to release in the test environment but not in production. A reliable fix names the timing dependency: kill orphan EXCEL.EXE explicitly (branch 2 stop-gap), confirm the preceding activity completed (use its output, not a guessed delay), or restructure the workflow so the dependency is explicit.
+
+- **"Wrap Write Range in a bare Try Catch and continue on error."** A bare Try-Catch that catches `Exception` / `BusinessException` / `COMException` and only logs without re-throwing turns Write Range failures into silent skips — the workflow proceeds as if the write succeeded, leaving the target workbook in a partial state. Downstream activities then operate on stale data, producing wrong outputs that are far harder to diagnose than the original exception. Use Try-Catch only with a real recovery path: retry with a smaller batch (branch 5 volume), mark the queue item Failed and abort, send a notification, or re-throw a domain-specific exception. The `Ignore empty source` property handles ONE specific case (branch 1's `Nothing`) — it is NOT a general "catch and continue" mechanism for any of the other branches.
+
+- **"Set `ExcludeHeaders=True` to silence the empty-source error."** This is a real fix ONLY when the workflow's intent is to write data rows without a header. Setting `ExcludeHeaders=True` to make branch 3 "go away" while the rest of the workflow still expects a header row produces a workbook with misaligned data — the data lands in the same column positions as the header would have, so the first data row overwrites whatever was at that position. Either correctly skip the write when there are no rows (branch 3's `If`-guard fix), or restructure the workflow so the header / data contract is explicit.
+
+- **"Downgrade `UiPath.Excel.Activities` to pre-2.8.5 to silence the hidden-rows error."** Branch 4's explicit error was added BECAUSE pre-2.8.5 versions silently wrote over hidden cells, causing data loss that workflow authors only discovered weeks later when human users unhid rows. Downgrading reintroduces the bug. The correct fix is to handle the hidden-rows case explicitly (unhide, restructure target range, or refactor).
+
+## Prevention (cross-branch)
+
+- Initialize all `DataTable` variables at declaration (e.g., `New DataTable()` assigned via `Variables` panel default value, OR an early `Build Data Table` on the execution path). Treat `Nothing` as never-valid for a DataTable in Write Range scope.
+- Log `DataTable.Rows.Count` and `DataTable.Columns.Count` immediately before every Write Range. Two log lines are cheap insurance against branches 1 and 3.
+- Guard Write Range with `If dt.Rows.Count > 0 Then` for any workflow where the source DataTable can legitimately be empty (filter results, query results, scraped data).
+- Set `ReadOnly: False` explicitly on Modern `Use Excel File` scopes that contain any write activity. The default is a footgun.
+- Avoid mixing Classic Workbook activities with Modern / Classic scope containers against the same workbook path in one workflow — the scope owns the file, and the standalone Workbook activity fails its own acquisition (branch 2's scope-conflict variant).
+- For workflows on a sheet that humans also edit: before any Write Range, insert a `Remove Data Filter` (Modern) or equivalent Classic step. AutoFilter state is invisible to the workflow author at design time but very visible to the activity at runtime (branch 4).
+- For workflows that aggregate or transform user-supplied content: sanitize formula-prefix characters (`=`, `+`, `-`, `@`) before writing. Treat any user-supplied string as potentially formula-shaped.
+- For large-volume writes (>20K rows): default to OpenXML provider, chunk into 5–20K-row batches, log per-batch progress. Plan for the volume case even if today's data fits.
+
+## Related
+
+- Other Excel Activities failure fingerprints (read-side and write-side cross-cuts — file-locked, sheet-not-found, protected-sheet) are separate playbooks; see [`../summary.md`](../summary.md) for navigation. Branch 2 (file lock) and the sheet-name and protected-sheet pivots in step 2 inherit the diagnostic chains from those playbooks.
+- [`./execute-macro-failures.md`](./execute-macro-failures.md) — sibling playbook for `Execute Macro` failures. Workflows that combine Write Range with VBA post-processing share the file-acquisition and scope-container surfaces.
+- [`../overview.md`](../overview.md) — package overview, including the scope-container model and the OpenXML-vs-COM provider distinction relevant to branch 5's volume sub-cause.
+- For headless workflows where the write target is best expressed in code rather than DataTable-to-range, consider migrating the relevant logic to the cloud surface via `o365-activities/` (Microsoft Graph API) — that surface has different memory semantics and no Excel COM dependency, avoiding branches 2, 4, and 5's volume variant entirely.

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

@@ -1,9 +1,14 @@
 # Excel Activities Presentation Rules
 
-- **Activities** — use the display name (e.g., "Invoke VBA", "Excel Process Scope", "Read Range"), not the fully qualified class name (e.g., `UiPath.Excel.Activities.Business.InvokeVBAX`)
-- **Workbooks** — refer to workbooks by their filename (e.g., "workbook 'Q3-Report.xlsx'") or full path when ambiguous; not by the variable holding the `WorkbookApplication` reference
-- **Worksheets / sheets** — refer to sheets by the tab name visible in Excel (e.g., "sheet 'Summary'"), not by index
-- **Code files** — refer to the VBA source file by filename and extension (e.g., "code file `macro.txt`" or "`InvoiceMacros.vba`"), not by the variable holding the path
-- **VBA macros** — refer to macros by the `Sub`/`Function` name as it appears in the code file (e.g., "macro `ImportInvoices`"), not by the `EntryMethodName` variable
-- **Office versions** — refer to Office by its installed product name and bitness (e.g., "Microsoft 365 Apps for Enterprise (64-bit)", "Office 2019 (32-bit)"), not by internal version numbers like `16.0` unless they are the only identifier available
-- **Excel settings** — refer to Trust Center settings by the exact UI label path the user navigates (e.g., `File > Options > Trust Center > Trust Center Settings > Macro Settings > Trust access to the VBA project object model`), so the user can find the toggle without guessing
+- **Activities** — use the display name in prose (e.g., "Read Range", "Write Range", "Use Excel File", "Invoke VBA"). Include the class name in parentheses on first mention so an agent can match a stack trace (e.g., "Read Range (`ReadRangeX`)"). Don't lead with the fully qualified class name (e.g., `UiPath.Excel.Activities.Business.InvokeVBAX`).
+- **Scopes** — distinguish "Excel Application Scope" (legacy, COM-only, requires Excel installed, holds Excel UI open) from "Use Excel File" / "Excel Process Scope" (modern, OpenXML by default, falls back to COM for unsupported features). When the scope matters for the diagnostic, name it explicitly.
+- **Providers** — call out "OpenXML provider" vs. "Excel COM" when the diagnostic depends on which one ran. The provider affects which exceptions are produced and which workbook features are supported.
+- **Workbooks** — refer to a workbook by its filename with parent context (e.g., "workbook `Q1-Forecast.xlsx` in `C:\Robot\Data\`"), not by full path on first mention and not by the variable holding the `WorkbookApplication` reference. Show the full path when the path itself is the subject of the error (file-not-found, UNC issues) or when the agent needs to inspect the host. Show casing exactly as the workflow configured it.
+- **Sheets** — refer to a sheet by its name in single quotes (e.g., "sheet 'Summary'", "sheet 'Q1 Data'"), not by index. Sheet name comparison is case-sensitive on the OpenXML provider and case-insensitive under Excel COM — when reporting a sheet-name mismatch, show both the configured name and the actual sheet names in the workbook verbatim.
+- **Ranges** — show ranges in A1 notation exactly as configured (e.g., `A1:D100`, `B2`, blank for used-range). Don't normalize, expand, or trim.
+- **Code files** — refer to the VBA source file by filename and extension (e.g., "code file `macro.txt`" or "`InvoiceMacros.vba`"), not by the variable holding the path.
+- **VBA macros** — refer to macros by the `Sub`/`Function` name as it appears in the code file (e.g., "macro `ImportInvoices`"), not by the `EntryMethodName` variable.
+- **Host processes** — when referencing Excel processes on the host, use the literal `EXCEL.EXE` (uppercase) — that's the name as it appears in Task Manager and `tasklist`. Distinguish a user-owned instance (Excel UI visible to a logged-in user) from an orphan (no UI, owned by the Robot's session or a prior job's session).
+- **Local file paths** — show the full local path as configured on the activity. Distinguish local paths from network paths (`\\server\share\...`) explicitly — lock semantics, latency, and permission models differ.
+- **Office versions** — refer to Office by its installed product name and bitness (e.g., "Microsoft 365 Apps for Enterprise (64-bit)", "Office 2019 (32-bit)"), not by internal version numbers like `16.0` unless they are the only identifier available.
+- **Excel settings** — refer to Trust Center settings by the exact UI label path the user navigates (e.g., `File > Options > Trust Center > Trust Center Settings > Macro Settings > Trust access to the VBA project object model`), so the user can find the toggle without guessing.

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

@@ -20,3 +20,9 @@
 | 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) |
+| Append Range Failures | Medium | `Append Range` (classic scoped) / `AppendRangeX` (modern scoped) / `Append Range Workbook` (standalone) fails. Signatures: `BusinessException` referencing missing `Excel Application Scope` / `Use Excel File`; `COMException 0x800A03EC Application-defined or object-defined error`; `BusinessException: The sheet with the name '<x>' does not exist`; `IOException: cannot access the file`; `NullReferenceException` on the activity; `BusinessException` mentioning "hidden rows" (package v2.8.5+). Causes: activity variant doesn't match the surrounding container (scoped activity outside a scope, OR Workbook activity colliding with a scope on the same path), sheet name mismatch or unsupported file extension for the active provider, workbook locked or read-only, uninitialized source DataTable, column schema mismatch between source DataTable and target sheet (count / order / types — appended by POSITION, not by header name), or hidden rows in the target append region. Includes anti-patterns section rejecting Delay-as-fix, bare-Try-Catch suppression, switch-to-Workbook-to-silence-scope-error, and pre-2.8.5 downgrade-to-silence-hidden-rows | [append-range-failures.md](./playbooks/append-range-failures.md) |
+| Delete Range Failures | Medium | `DeleteRange` (classic) / `DeleteRangeX` (modern) fails. Signatures: `ArgumentException: The range is invalid` / `The string argument cannot be empty`; `COMException` referencing the shift operation or `Application-defined or object-defined error` (`0x800A03EC`); `IOException` / `COMException` with "cannot access the file"; or no exception with wrong rows removed. Causes: activity outside its required scope (`Excel Application Scope` / `Use Excel File`), invalid or empty `Range` syntax, `ShiftCells`/`ShiftOption` conflict with merged cells / Excel Tables, workbook locked or read-only, or AutoFilter hiding rows in the target block. Includes anti-patterns section rejecting Delay-as-fix, bare-Try-Catch suppression, and Delete-Range-when-Clear-Range-was-meant | [delete-range-failures.md](./playbooks/delete-range-failures.md) |
+| Excel Application Scope (Classic) COM-Interop Failures | Medium | A SINGLE Classic `Excel Application Scope` (`ExcelApplicationScope`, COM-only) fails at the COM layer on a host that DOES have Excel. Signatures: `BusinessException: Error opening workbook. Make sure Excel is installed.` with inner `COMException 0x8002801D TYPE_E_LIBNOTREGISTERED` (or `0x80040154` despite a confirmed install); `BusinessException: Failed opening the Excel file. Possible reasons: file is corrupt, already used by another process or password protected.`; `InvalidCastException` on `System.__ComObject` with `0x80004002 E_NOINTERFACE`. Causes: COM registration / type-library corruption after an Office upgrade or repair (Excel present, interop broken); workbook held by an orphan `EXCEL.EXE` from a crashed prior job or a user-opened instance; a COM add-in (commonly `UiPath.Integration.ExcelAddin`) corrupting the interop QueryInterface. Fixes: Office Online Repair / UiPath Repair Tool / targeted `TypeLib` cleanup; clear orphan processes (`Kill Process EXCEL` on dedicated unattended hosts only) and fix what leaves orphans; disable the offending COM add-in. Includes anti-patterns rejecting Delay-as-fix, bare-Try-Catch suppression, full Office reinstall over repair, unconditional `Kill Process EXCEL` on shared hosts, and Visible-True-to-debug. Cross-references the card playbook for shared branches (true not-installed, path, multi-scope race, child-outside-scope, sensitivity) | [excel-application-scope-failures.md](./playbooks/excel-application-scope-failures.md) |
+| Use Excel File / Excel Application Card Failures | Medium | The Modern scope container `ExcelApplicationCard` (Use Excel File) or Classic `Excel Application Scope` fails to open the workbook or govern its lifecycle. Signatures: `BusinessException: Error opening workbook. Make sure Excel is installed.`; `ArgumentException: Excel File path is empty or not set` / `Illegal characters in path`; `COMException RPC_E_SERVER_UNAVAILABLE` (`0x800706BA`) / `RPC_E_DISCONNECTED` (`0x80010108`) / `CO_E_SERVER_EXEC_FAILURE` (`0x80080005`); `BusinessException` on a child activity about missing scope; `COMException` / `BusinessException` referencing sensitivity label or information protection. Causes: Excel not installed or Interop broken (Classic always needs COM; Modern needs COM when COM-forcing properties are set or `.xls`/`.xlsb` files are involved); empty / null / illegal `WorkbookPath` from variable scope drift or upstream producer returning empty; COM/RPC race across multiple scopes without an `Excel Process Scope` wrapper (or a child macro tore down EXCEL.EXE); Modern child activity dropped outside any card (cross-cut to per-activity playbooks); Microsoft Purview / AIP sensitivity-label rejection on pre-v2.23.4 packages or v2.23.4+ without the SensitivityLabel/Operation properties configured. Includes anti-patterns section rejecting Delay-as-fix, bare-Try-Catch suppression, Visible-True-to-debug (a COM-forcing footgun), and package-downgrade-to-silence-sensitivity-label | [excel-application-card-failures.md](./playbooks/excel-application-card-failures.md) |
+| Execute Macro / Run Spreadsheet Macro Failures | Medium | VBA macro invoked via `ExecuteMacro` (classic) or `Run Spreadsheet Macro` (modern) fails — most commonly `System.Runtime.InteropServices.COMException` with HRESULTs `0x80020009 DISP_E_EXCEPTION`, `0x800AC472`, or `0x80010108 RPC_E_DISCONNECTED`; sometimes a job hang with no exception when Excel surfaces a modal dialog. Causes: macro name not in workbook, VBA error inside the macro, macro tears down Excel (Workbooks.Close / Application.Quit), modal dialog (MsgBox / InputBox / debug break) blocking COM, macros disabled by Trust Center policy on the Robot host, concurrent COM access (STA apartment violation), or missing add-in / ActiveX dependency. Includes anti-patterns section rejecting Delay-as-fix and bare-Try-Catch suppression | [execute-macro-failures.md](./playbooks/execute-macro-failures.md) |
+| Write Range Failures | Medium | `WriteRange` (classic) / `WriteRangeX` (modern) fails. Signatures: `NullReferenceException` on the activity; `IOException`/`COMException` "cannot access the file"; `BusinessException` mentioning "empty source" / "Ignore empty source" / "header"; `BusinessException` mentioning "hidden rows" / "hidden columns" (package v2.8.5+); `OutOfMemoryException` or `COMException 0x800A03EC`. Causes: uninitialized `DataTable` variable (preceding step skipped or variable scope drift), workbook locked or read-only (orphan EXCEL.EXE / Mark as Final / Modern scope `ReadOnly=True`), empty source DataTable with `ExcludeHeaders=False`, hidden rows or columns inside the target write range, oversized batches or formula-prefix characters (`=`, `+`, `-`, `@`) misinterpreted as broken formulas. Includes anti-patterns section rejecting Delay-as-fix, bare-Try-Catch suppression, ExcludeHeaders-to-silence-empty-source, and pre-2.8.5 downgrade-to-silence-hidden-rows | [write-range-failures.md](./playbooks/write-range-failures.md) |

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/investigation_guide.md

@@ -15,6 +15,7 @@ If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy.
 ## Domain-Specific Data Gathering
 
 1. **Activity execution traces** — these activities emit per-call traces. Pull them when available — they expose the exact Google REST endpoint hit, request/response status, and timing. Trace evidence narrows whether the failure originated at connection resolution, OAuth token validation, the Google API call, or post-processing inside the activity.
+2. **Route by status class and exception type, not by the message sentence.** Modern `*Connections` activities wrap most failures into a `GSuiteException` whose *text* is a friendly mapping of the underlying HTTP status — different root causes share similar wording, and one generic message (`An error occurred in the activity.`) hides the real status entirely. Before matching a playbook, read the embedded HTTP status / inner exception from the trace and classify: **401** (token rejected) and **403** (authorization/quota) and auth-phase `TimeoutException` → connection/auth or storage-quota; **404** / unresolved item → resource-not-found; **400** server-side range/cell → the Sheets playbooks; **5xx / 429 / network `HttpRequestException` / per-request `A task was canceled.`** → transient-and-timeout. Note two specific traps: a per-request timeout surfaces as `TaskCanceledException` (`A task was canceled.`), **never** as `System.TimeoutException` (which only comes from authentication); and a client-side `ArgumentException`/`NullReferenceException` (invalid/null input) is thrown before any API call, so it has no HTTP status at all.
 
 ## Testing Prerequisites