@uipath/skills 1.196.0 → 1.197.0

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

@@ -0,0 +1,146 @@
+---
+confidence: medium
+---
+
+# Append Range Failures
+
+## Context
+
+A `UiPath.Excel.Activities` `Append Range` activity appends a `DataTable`'s rows to the bottom of an existing sheet, after the last row containing data. The package exposes the operation through three surfaces with materially different runtime semantics:
+
+1. **Classic `Append Range` inside `Excel Application Scope`** — opens the workbook through Excel COM; requires Excel installed on the host. Inherits the scope's open workbook reference.
+2. **Modern `Append Range` (`AppendRangeX`) inside `Use Excel File`** — opens the workbook through the OpenXML provider (default) or falls back to Excel COM when scope properties force it.
+3. **Classic `Append Range Workbook`** — the standalone Workbook surface that reads / writes the file's raw bytes directly without an enclosing scope and without requiring Excel installed.
+
+Failures originate at one of six surfaces: activity-variant mismatch (wrong surface for the deployment), sheet-name or file-extension resolution, file acquisition (workbook locked), source-table integrity (null DataTable), source-vs-target schema alignment (columns don't match the existing sheet), or target-region structural state (hidden rows on the append target under package v2.8.5+).
+
+What this looks like — Append Range faults surface as one of these signatures:
+
+- `UiPath.Excel.BusinessException` referencing "must be placed inside an `Excel Application Scope`" or "must be placed inside a `Use Excel File`" — the activity variant in the workflow doesn't match its surrounding container (or has no container). Branch 1.
+- `System.Runtime.InteropServices.COMException (0x800A03EC): Application-defined or object-defined error` — Excel COM rejected the operation. For Append Range, two distinct underlying causes share this HRESULT: branch 2 (sheet name mismatch or unsupported file extension passed to a COM-only call) and branch 5 (the cell write itself rejected due to a schema mismatch). Distinguish by the surrounding evidence (logs, target inspection).
+- `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 scope. Branch 3.
+- `System.NullReferenceException: Object reference not set to an instance of an object.` — the configured `DataTable` argument is `Nothing`. Branch 4.
+- `UiPath.Excel.BusinessException` mentioning "hidden rows" or "hidden columns" — the calculated append region intersects hidden rows on the target sheet (package v2.8.5+ only). Branch 6.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Activity variant mismatch (Append Range vs Append Range Workbook vs AppendRangeX)** — three surfaces with the same display name but different acquisition models. The classic `Append Range` activity dropped outside an `Excel Application Scope` throws a `BusinessException` at runtime because it has no workbook context. The Modern `Append Range` (`AppendRangeX`) outside a `Use Excel File` throws the equivalent. The standalone `Append Range Workbook` works independently and does NOT require a scope — but it accesses the file via direct bytes, so it can't coexist with an outer scope that already holds the workbook. Mixing surfaces against the same path in one workflow self-deadlocks on the file lock (collapses to branch 3's scope-conflict variant).
+2. **Sheet name mismatch or invalid file extension** — the configured `SheetName` doesn't match any sheet in the workbook (typo, OpenXML case-sensitivity, sheet renamed upstream, leading/trailing whitespace), OR the workbook path uses an extension Excel COM doesn't recognize for write (`.xls` without the older Excel format support installed, `.xlsm` against an OpenXML-only call). Both surface with the generic `0x800A03EC` HRESULT or a more specific `BusinessException: The sheet with the name '<x>' does not exist` depending on package version. Cross-cuts the read-range sheet-not-found surface — the diagnostic is identical.
+3. **Workbook locked or opened read-only** — same fault family as the read-range / write-range / delete-range file-locked surface: a different process holds the file (user-opened Excel UI, orphan `EXCEL.EXE` from a prior job, AV scanner, network-share lock from a different host), the file is read-only at the OS layer (NTFS ACL, `Mark as Final`, Protected View), OR the workflow mixes the Workbook surface with a Modern/Classic scope against the same path (the scope owns the file; the standalone Workbook activity refuses to acquire it).
+4. **Uninitialized / null DataTable** — the source `DataTable` argument is `Nothing`. Causes: variable declared but never assigned (missing `Build Data Table` / `Read Range` step); preceding step skipped on a conditional branch; conditional output from `Filter DataTable` against an empty source that returned `Nothing` instead of an empty DataTable; variable-name typo so the activity reads the wrong scope's variable.
+5. **Column schema mismatch (source DataTable vs target sheet)** — Append Range expects the source `DataTable`'s columns to align with the existing target sheet's header row. Common failure modes: the source has more columns than the target (extra columns spill into never-defined positions); the source has fewer columns (the activity may write into the wrong starting column, depending on `AddHeaders` and how the activity computes the append-start cell); column-type mismatches (e.g., source numeric column → target text column with stored-as-text values causes Excel to reject the write); column-order mismatches (Append writes by position, NOT by header name — so swapping two columns in the source produces a structurally-valid but semantically-corrupted append). Surfaces as `COMException 0x800A03EC` from `Range.set_Value`, OR a `BusinessException` referencing column count, OR a silent semantic corruption (no error, wrong column gets the wrong data — same pattern as branch 5 of delete-range / branch 5 of filter misalignment).
+6. **Hidden rows in the target append region (package v2.8.5+)** — the workbook's target sheet has rows hidden where the append would land (the row immediately after the last visible data row, OR hidden rows between the last data row and a re-emerging data block). Pre-2.8.5 versions silently wrote into the hidden cells; 2.8.5+ throws an explicit `BusinessException` flagging the hidden range so the workflow author catches the data-shape risk. Common trigger: an AutoFilter applied to the target sheet that hides rows including or following the last-data row position.
+
+What to look for:
+
+- **The exception class and message** — first signal. `BusinessException` referencing missing scope → branch 1. `0x800A03EC` / `BusinessException` about sheet → branch 2 (or branch 5 if the sheet exists but columns mismatch). `IOException` / "cannot access the file" → branch 3. `NullReferenceException` → branch 4. `BusinessException` mentioning column count or wrong-type cell rejection → branch 5. `BusinessException` mentioning "hidden rows" → branch 6.
+- **Workflow source** — which `Append Range` surface (Classic scoped / Modern scoped / Workbook standalone), the configured `DataTable` argument, `SheetName`, `AddHeaders`, the workbook path (including the extension), and the parent container.
+- **The DataTable's source and shape** — what activity produced the source (`Build Data Table`, `Read Range`, `Generate Data Table`, etc.), how many columns it has, what column types and headers it carries. Required to confirm or rule out branches 4 and 5.
+- **Target sheet's existing structure** — header row content (matters for branch 5's column-alignment check), hidden rows (branch 6), AutoFilter state, the last row containing data (branch 6 / branch 5).
+- **Package version** — `UiPath.Excel.Activities` version from `project.json`. Branch 6 is version-gated at 2.8.5; pre-2.8.5 produces silent corruption with no exception.
+- **Workbook extension** — `.xlsx`, `.xlsm`, `.xls`, `.xlsb`. The Modern scope's OpenXML provider supports `.xlsx` / `.xlsm` cleanly; `.xls` (legacy binary) requires COM. Branch 2's extension-mismatch variant lives here.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, activity surface, and configuration.** From `uip or jobs get <job-key> --output json` → `Info`: exception class, full message, HRESULT (if a COMException), inner exception. From workflow source: the Append Range surface (Classic scoped / Modern scoped / Workbook standalone), parent container, configured `SheetName`, `AddHeaders`, the source DataTable variable, and the workbook path. From job logs (`uip or jobs logs <key>`): the activity's Trace lines, plus any `Log Message` lines capturing the DataTable shape before the activity.
+
+2. **Branch the diagnostic on the exception signature.**
+   - `BusinessException: ... must be placed inside an Excel Application Scope` / `... inside a Use Excel File` → branch 1; go to step 3.
+   - `BusinessException: The sheet with the name '<x>' does not exist` → branch 2; pivot to the read-range sheet-not-found playbook for the full chain (see [`../summary.md`](../summary.md)).
+   - `IOException` / `COMException` with "cannot access the file" / "used by another process" → branch 3; pivot to the read-range file-locked playbook (see [`../summary.md`](../summary.md)).
+   - `NullReferenceException` → branch 4; go to step 4.
+   - `COMException 0x800A03EC` without explicit sheet-name or hidden-rows language → branches 2 (extension / sheet) or 5 (column schema); go to step 5.
+   - `BusinessException` mentioning "hidden rows" / "hidden columns" → branch 6; go to step 6.
+
+3. **Confirm branch 1 (activity variant mismatch).** Inspect the workflow source. Three sub-cases:
+   - The activity is **classic `Append Range`** (not the `Workbook` variant) and there is NO surrounding `Excel Application Scope`. Fix is structural: either wrap it in a scope OR switch to the standalone `Append Range Workbook` activity.
+   - The activity is **Modern `Append Range` (`AppendRangeX`)** and there is NO surrounding `Use Excel File`. Same fix family: wrap in Modern scope OR switch surface.
+   - The activity is **`Append Range Workbook`** (standalone) but the workflow ALSO has an `Excel Application Scope` / `Use Excel File` open against the same path elsewhere — that scope holds the file, the standalone Workbook surface can't acquire it. This is the scope-conflict variant of branch 3 in disguise; resolve by replacing the standalone Workbook activity with a scoped one nested inside the existing scope, OR remove the scope and use only the Workbook surface throughout.
+
+4. **Confirm branch 4 (uninitialized DataTable).** Trace the `DataTable` argument's variable backward in the workflow source. Find the most recent assignment / output binding. If it's an upstream `Read Range`, did that activity succeed in this run (check job logs)? If it's `Build Data Table`, is the activity actually on the execution path? If the variable was declared in an inner scope, has it gone out of scope by the time Append Range runs? Add a `Log Message Level=Info Message=$"src rows={dt.Rows.Count}, cols={dt.Columns.Count}"` immediately before the activity and rerun — if that line throws NRE, the variable is null. The diagnostic chain is identical to Write Range's branch 1; the same fixes apply.
+
+5. **Distinguish branch 2 (sheet/extension) from branch 5 (column schema) when both surface as `0x800A03EC`.** Both branches share the same generic Excel HRESULT and can produce the same `Range.set_Value` stack frame. Differentiate with these checks:
+   - **Sheet existence**: open the workbook in Excel (or read its sheet list via `Get Workbook Sheets`). If the configured `SheetName` does not match any sheet → branch 2 (sheet name). If the sheet exists → continue.
+   - **Extension support for the provider**: read the workbook path's extension. The Modern OpenXML provider supports `.xlsx` and `.xlsm`. The Workbook surface supports `.xlsx`, `.xlsm`, `.xlsb`, `.xls` natively without Excel. The Classic Excel scope supports whatever the installed Excel version supports. A `.xls` (legacy binary) against a Modern scope's OpenXML provider can throw 0x800A03EC; switching to COM mode (or replacing with a Workbook surface) fixes it.
+   - **Source vs. target column alignment**: open the target workbook in Excel. Inspect the target sheet's existing header row and the column data types of the last-data row. Compare to the source DataTable's columns (count, names, types). If the source has more columns than the target, OR a source column's type doesn't match the target's stored type at that position, OR the source column order differs from the target's header order → branch 5 (schema mismatch).
+
+6. **Confirm branch 6 (hidden rows in target append region).** Two checks:
+   - **Package version**: read `UiPath.Excel.Activities` from `project.json`. If < 2.8.5, branch 6 doesn't exist in this version — recheck the exception text against other branches. If ≥ 2.8.5, continue.
+   - **Target sheet hidden state**: open the workbook in Excel before running the workflow. Locate the last row that contains data on the target sheet. Inspect the rows immediately after (where the append would land) and any rows between data blocks. Look for: AutoFilter funnel icons (active filter hiding rows); manually hidden rows (gap in row numbers); grouped rows collapsed. Any of these in the append target triggers branch 6.
+
+The root cause is **which of the six surfaces** the failure maps to. A confirmed finding names the activity surface (Classic scoped / Modern scoped / Workbook standalone), the source DataTable's runtime shape, the target sheet's structure, and the matching exception signature.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Activity variant mismatch:**
+  - **Classic `Append Range` outside `Excel Application Scope`**: wrap it in `Excel Application Scope` with the workbook path configured on the scope. If the Robot host doesn't have Excel installed (common for headless / unattended Robots), switch to the standalone `Append Range Workbook` activity instead — it doesn't require Excel and works on the file's raw bytes.
+  - **Modern `AppendRangeX` outside `Use Excel File`**: wrap it in `Use Excel File` with the workbook configured on the scope.
+  - **`Append Range Workbook` alongside another scope on the same path**: replace the standalone Workbook activity with a scoped one nested inside the existing scope. Don't mix surfaces against the same file in one workflow — the scope and the Workbook surface acquire the file by different mechanisms and self-deadlock.
+  - Prevention: pick one Excel surface (Classic, Modern, or Workbook) per workbook path in a workflow, and stick to it. Mixing surfaces is the leading cause of self-inflicted file-acquisition failures.
+
+- **Branch 2 — Sheet name mismatch or invalid file extension:**
+  - **Sheet mismatch**: apply the resolution from the read-range sheet-not-found playbook (see [`../summary.md`](../summary.md) for navigation). Correct the configured `SheetName` to match the workbook's actual sheet name verbatim — including case under OpenXML, whitespace, and Unicode normalization. Validate dynamic expressions with `Get Workbook Sheets` at workflow start before the Append Range runs.
+  - **Extension mismatch**: confirm the workbook extension is compatible with the activity surface. `.xls` files require Excel COM (Classic scope or Workbook with appropriate installation); `.xlsb` requires the Workbook surface. If the Modern scope is forcing OpenXML on a non-OpenXML extension, either change the workbook to `.xlsx` (re-save in Excel) or switch to a surface that supports the extension natively.
+
+- **Branch 3 — Workbook locked or read-only:**
+  - Apply the resolution from the read-range file-locked playbook (see [`../summary.md`](../summary.md) for navigation). The append side 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 workflow mixes scope surfaces against the same path.
+  - For `Append Range Workbook` against a path also referenced by an outer scope: pick one surface (see branch 1's prevention rule).
+
+- **Branch 4 — Uninitialized / null DataTable:**
+  - Initialize the variable at declaration (`New System.Data.DataTable()` as the default). With an initialized empty DataTable, the failure shifts to whichever case actually applies (likely a no-op append, or branch 5 if columns don't align).
+  - Guard the Append Range with `If dt IsNot Nothing AndAlso dt.Rows.Count > 0 Then` and skip on the empty case.
+  - Trace the upstream populating activity to ensure it actually executes in every execution path that reaches Append Range. The diagnostic chain is identical to Write Range's branch 1.
+
+- **Branch 5 — Column schema mismatch:**
+  - **Align columns by position** (the activity writes by position, not by header name):
+    - Confirm the source DataTable's columns match the target sheet's column order, count, and types.
+    - For mismatched ORDER: reorder the source DataTable's columns via `dt = dt.DefaultView.ToTable(False, "Col1", "Col2", "Col3")` (the second argument is the column-name list in target-sheet order).
+    - For extra source columns: select only the target's columns via the same `ToTable(False, ...)` call.
+    - For missing source columns: add the missing columns to the source DataTable (`dt.Columns.Add("MissingCol")`) so the append fills them — even if the values are empty/null.
+  - **Align column types**:
+    - Check the target sheet's actual storage type per column (not just the header label). A column showing "1234" rendered right-aligned is numeric; "1234" left-aligned with a green corner triangle is stored as text. Source values must match.
+    - Use `Convert.ToString(...)`, `Convert.ToDecimal(...)`, etc. on the DataTable's row population step to coerce types before the append.
+  - **Disambiguate AddHeaders behavior**: if the target sheet already has a header row and the source DataTable also carries headers, set `AddHeaders=False` on the activity so the source headers aren't duplicated as a data row in the target.
+  - Prevention: when designing an Append Range workflow, document the target's column contract (column names, positions, types) and apply it as a transformation step on the source DataTable before the append. Don't rely on the source's natural column order to match the target's.
+
+- **Branch 6 — Hidden rows in target append region (package v2.8.5+):**
+  - Remove hidden rows from the target append zone before the Append Range:
+    - **Active AutoFilter**: insert a `Remove Data Filter` (Modern) or `Filter Range Action=Remove` (Classic) immediately before Append Range. After the append, re-apply the filter if downstream consumers depend on it.
+    - **Manually hidden rows**: unhide programmatically (`Worksheet.Rows.Hidden = False` via COM) or in Excel before deployment.
+    - **Grouped rows collapsed**: expand the group before the append.
+  - If the hidden state is intentional and the append region must not be reorganized, route the append to a different sheet whose layout is robot-controlled, then have a downstream step (separate workflow) consolidate the data into the user-facing sheet.
+  - Downgrading the package to pre-2.8.5 to silence the error is the playbook's anti-pattern — it reintroduces the silent-data-loss bug that the explicit error was added to catch.
+
+## Anti-patterns (what NOT to do)
+
+Common advice for Append 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 Append Range."** A Delay is a workaround for a race condition or initialization issue that the workflow author has not diagnosed. For Append Range, the most common temptation is to add a delay after opening the workbook (masking branch 3) or after a preceding write operation (masking a timing dependency that the workflow should encode explicitly). The Delay works intermittently and hides the real cause. Fix the underlying timing (kill orphan EXCEL.EXE for branch 3; sequence activities correctly so the dependency is explicit).
+
+- **"Wrap Append 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 Append Range failures into silent partials — Excel COM may have appended SOME rows before rejecting at a problem row, and the catch turns the partial write into a "success" with stale / missing data in the target. Downstream consumers reading the target then operate on a corrupted append. Use Try-Catch only with a real recovery path: retry with cleaned data (branches 4 and 5), notify on persistent file-lock (branch 3), or re-throw a domain-specific exception.
+
+- **"Switch to Append Range Workbook to silence the scope error."** The standalone Workbook surface IS a legitimate alternative when the deployment host doesn't have Excel installed. But switching to it WITHOUT understanding why the original scoped activity was failing can mask real bugs — e.g., a workflow that needed COM features (formula recalculation, conditional formatting interaction) will silently produce wrong data with the Workbook surface even though the failure goes away. Pick the surface based on the deployment requirements (does the workflow need Excel features? is Excel installed on the host?), not based on which one stops throwing.
+
+- **"Downgrade `UiPath.Excel.Activities` to pre-2.8.5 to silence the hidden-rows error."** Branch 6's explicit error was added BECAUSE pre-2.8.5 versions silently appended over hidden rows, 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 (remove the filter, unhide, or route to a different sheet).
+
+## Prevention (cross-branch)
+
+- Pick one Excel surface per workbook path per workflow. Classic scoped, Modern scoped, OR Workbook standalone — don't mix. Mixing causes branch 1's scope-conflict variant of branch 3.
+- Document the target sheet's column contract (order, types, header row presence) and apply it as an explicit transformation step on the source DataTable before Append Range. Branch 5's column-mismatch failures are far cheaper to diagnose when the alignment is explicit.
+- Initialize all `DataTable` variables at declaration (default to `New DataTable()`). Combined with an `If dt.Rows.Count > 0` guard, this handles both branch 4 (null) and the empty-case no-op cleanly.
+- Log `DataTable.Rows.Count` and `DataTable.Columns.Count` immediately before every Append Range. The two-line log makes branches 4 and 5 self-diagnosing.
+- For workflows on a sheet that humans also edit: insert a `Remove Data Filter` (Modern) or equivalent Classic step before every Append Range. AutoFilter state is invisible to the workflow author at design time but very visible to the activity under v2.8.5+ (branch 6).
+- For Robot hosts WITHOUT Excel installed: prefer the `Append Range Workbook` surface package-wide. The Classic / Modern scopes will fail at acquisition; the Workbook surface won't.
+- For workbooks accessed by multiple workflows: serialize Excel access (single-performer queues, host-level locks) to prevent branch 3 collisions between concurrent jobs.
+
+## 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. Branches 2 (sheet) and 3 (file lock) inherit the diagnostic chains from those playbooks.
+- [`./delete-range-failures.md`](./delete-range-failures.md) — sibling range-mutation playbook. The hidden-rows / AutoFilter pattern (branch 6 here / branch 5 there) is structurally identical in both directions; the fix for one applies to the other.
+- [`./execute-macro-failures.md`](./execute-macro-failures.md) — sibling playbook for `Execute Macro` failures. Workflows that combine Append Range with VBA post-processing share the scope-container and file-acquisition surfaces.
+- [`../overview.md`](../overview.md) — package overview, including the scope-container model and the OpenXML-vs-COM provider distinction relevant to branches 1 and 2.
+- For headless workflows where the append target is best expressed in code rather than DataTable-to-sheet, consider migrating to the cloud surface via `o365-activities/` (Microsoft Graph API). That surface has different memory and concurrency semantics and no Excel COM dependency, avoiding branches 1, 3, and 6 entirely.

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

@@ -0,0 +1,126 @@
+---
+confidence: medium
+---
+
+# Delete Range Failures
+
+## Context
+
+A `UiPath.Excel.Activities` `Delete Range` activity (Classic `DeleteRange` inside `Excel Application Scope`, or Modern `DeleteRangeX` inside `Use Excel File`) removes a rectangular range from a worksheet, optionally shifting remaining cells. Failures originate at one of five surfaces: structural (no enclosing scope), range syntax (malformed or empty `Range`), shift configuration (`ShiftCells` / `ShiftOption` conflict with range geometry), file acquisition (workbook locked / read-only), or row alignment (active AutoFilter hides rows in the target block).
+
+What this looks like — Delete Range faults surface as one of these signatures:
+
+- Studio shows a validation error on the activity, or the workflow throws at runtime before the activity executes — typically `BusinessException: Excel Application Scope not found` or a Modern equivalent. Branch 1.
+- `System.ArgumentException: The range is invalid` or `System.ArgumentException: The string argument cannot be empty` — branch 2.
+- `System.Runtime.InteropServices.COMException` from Excel referencing the shift operation, or `Application-defined or object-defined error` (`0x800A03EC`) raised when the shift direction conflicts with surrounding data — branch 3.
+- `System.Runtime.InteropServices.COMException: Excel cannot access the file '<path>'` or `System.IO.IOException: The process cannot access the file ... because it is being used by another process.` — branch 4.
+- The activity completes without an exception but the wrong rows are removed / remaining rows misalign, or a subsequent activity throws because expected rows are no longer where the workflow assumed — branch 5.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Activity outside an Excel scope container** — Classic `Delete Range` placed outside an `Excel Application Scope`, or Modern `Delete Range` placed outside a `Use Excel File`. Studio flags this as a design-time validation error; if the project was packaged anyway (e.g., validation suppressed, scope removed after publish), the workflow throws at runtime before the activity runs. See [`../overview.md`](../overview.md) for the scope model.
+2. **Invalid range syntax or empty Range property** — `Range` is blank, quoted incorrectly, or uses non-A1 notation. Examples that fail: empty string, `Sheet1!A1:B10` (sheet prefix belongs in `SheetName`, not in `Range`), `R1C1:R10C2` (R1C1 notation), `A 1:B 10` (whitespace inside the address), unbalanced quotes from an expression that produced an empty literal. Same fault for both `A1:B10` (rectangular) and `A:E` / `1:10` (full-column / full-row) shapes — the syntax just has to parse.
+3. **ShiftCells / ShiftOption conflict** — `ShiftCells` is True but `ShiftOption` is unset, set to a direction the range geometry cannot satisfy, or set to a direction that violates surrounding sheet structure (e.g., `ShiftUp` on a range whose bottom edge touches a merged region; `EntireRow` on a range that intersects a structured Table). Symptom: COMException with the Excel `Application-defined or object-defined error` text, sometimes with HRESULT `0x800A03EC`. May also manifest as a silent data corruption if Excel partially executed the shift before erroring.
+4. **Workbook locked or opened read-only** — same fault family as Read Range / Write Cell file-locked: another process holds the workbook (orphan `EXCEL.EXE` from a prior job, a user has the file open in Excel UI, a different host has the lock on a network share), or the file is read-only at the OS layer (NTFS ACL, share-level permission, `Mark as Final`, Protected View on a downloaded copy). Delete Range is a write — read-only acquisition will fail it the same way it fails Write Range. The full investigation chain is shared with the read-range file-locked playbook; see [`../summary.md`](../summary.md) for navigation.
+5. **Range misalignment over filtered data** — the worksheet has an active AutoFilter (`Data → Filter`) that hides rows in or around the target range. Delete Range operates on the cell coordinates as configured, not the visible rows; when shifting is enabled, hidden rows get pulled into the deletion or remaining rows shift onto cells the user expected to be empty. Symptom: activity completes without an exception, but post-condition checks fail or downstream activities see unexpected rows. May also throw if the filter range overlaps the deletion range in a way Excel's COM rejects.
+
+What to look for:
+
+- **The exception class and message** — first signal. `ArgumentException` with "range is invalid" / "argument cannot be empty" → branch 2. `BusinessException` referencing "Excel Application Scope" or "Use Excel File" → branch 1. `COMException` / `IOException` with "cannot access the file" → branch 4. `Application-defined or object-defined error` referencing shift / direction → branch 3. No exception but wrong output → branch 5.
+- **Workflow source** — which `Delete Range` surface (Classic / Modern), the parent container (`Excel Application Scope` / `Use Excel File` / none), and the configured `Range`, `SheetName`, `ShiftCells`, `ShiftOption`. A literal `Range` value vs. an expression matters: branch 2 is most common when `Range` is an expression that resolved to empty / null at runtime.
+- **Workbook state at fault time** — open in Excel by a user (Win32 GUI), held by orphan `EXCEL.EXE`, marked read-only, filtered with `Data → Filter` active. The `Data → Filter` toggle leaves a visible filter dropdown on the header row; check by opening the workbook before the workflow runs and confirming no funnel icons appear on column headers.
+- **Sheet structure around the target range** — merged cells in or adjacent to the range, Excel Tables (`Ctrl+T` structured ranges) overlapping the range, freeze panes, named ranges that reference the deletion target. Any of these can convert a benign shift into a `0x800A03EC`.
+- **Whether the intent is to clear data or restructure the sheet** — Delete Range with `ShiftCells: False` clears cell values (similar to `Clear Range` but also removes formats). If the workflow only needs to clear values without affecting cell layout / formatting, the correct activity is `Clear Range` — using Delete Range is a category error that surfaces as branches 3 or 5.
+
+## 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 and full message. From workflow source: the `Delete Range` surface (Classic / Modern), parent container, configured `SheetName`, `Range`, `ShiftCells`, `ShiftOption`. From job logs (`uip or jobs logs <key>`): the activity's Trace lines for resolved runtime values.
+
+2. **Branch the diagnostic on the exception signature.**
+   - Studio validation error or `BusinessException` referencing the missing scope → branch 1; go to step 3.
+   - `ArgumentException` with "range is invalid" / "argument cannot be empty" → branch 2; go to step 4.
+   - `COMException` / `Application-defined or object-defined error` referencing shift / direction → branch 3; go to step 5.
+   - `IOException` / `COMException` with "cannot access the file" / "used by another process" / "read-only" → branch 4; pivot to the read-range file-locked playbook for the full chain (see [`../summary.md`](../summary.md)).
+   - No exception but wrong output / downstream failure → 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 for the full chain (see [`../summary.md`](../summary.md)). The diagnostic is identical to the read-side version.
+
+3. **Confirm branch 1 (no scope container).** Inspect the workflow source. Trace the activity tree from `Delete Range` upward. The activity must have an ancestor that is either `Excel Application Scope` (Classic) or `Use Excel File` (Modern), with the configured `Workbook` / `WorkbookPath` matching the file Delete Range is meant to operate on. If the activity is at the root of the workflow, or inside a `Sequence` / `Try Catch` with no enclosing Excel scope, branch 1 is confirmed.
+
+4. **Confirm branch 2 (invalid range syntax).** Examine the configured `Range` value:
+   - If literal: check for empty string, unbalanced quotes, sheet prefix (`Sheet1!A1`), R1C1 notation, or whitespace inside the address. Valid forms: `"A1:B10"` (rectangle), `"A:E"` (full columns), `"1:10"` (full rows), `"A1"` (single cell).
+   - If expression: log the resolved value immediately before the activity (`Log Message Level=Info Message=$"Range: '{rangeExpr}'"`) and rerun. The most common cause is an expression that produces an empty string from a null `DataRow` field, a `String.Format` against a `Nothing` value, or a slice that resolved to zero cells.
+   - If the expression depends on values computed earlier in the workflow (`row counts`, `lastRow`), confirm those values are valid at the moment Delete Range runs. A `lastRow` of 0 with a range expression like `"A1:B" + lastRow.ToString` produces `"A1:B0"`, which Excel COM rejects.
+
+5. **Confirm branch 3 (ShiftCells / ShiftOption conflict).** Inspect the activity configuration:
+   - If `ShiftCells` is False, this branch does not apply — go back to step 2.
+   - If `ShiftCells` is True, `ShiftOption` must be set to a valid direction. Classic `Delete Range` accepts `ShiftLeft` / `ShiftUp` / `EntireRow` / `EntireColumn`; Modern `DeleteRangeX` accepts `ShiftCellsLeft` / `ShiftCellsUp` / `EntireRow` / `EntireColumn` (naming differs slightly across versions — check the property dropdown for the host's package version).
+   - Open the workbook in Excel and inspect the deletion target's surroundings: are there merged cells along the bottom edge (relevant for `ShiftUp`), the right edge (relevant for `ShiftLeft`), or anywhere Excel would need to break to perform the shift? Are there Excel Tables (`Ctrl+T`) overlapping the range? Excel Tables refuse partial-row deletions that would break the table's rectangular shape.
+   - Reproduce manually: open the workbook in Excel, select the same range, `Home → Delete → Delete Cells…`, pick the same shift direction. If Excel rejects it interactively, the activity sees the same rejection wrapped in a COMException.
+
+6. **Confirm branch 5 (filter misalignment).** Open the workbook in Excel before running the workflow, OR snapshot it from a recent backup:
+   - Check each worksheet header row for the filter funnel icon (`Data → Filter` toggle). If active, the filter is applied — hidden rows exist.
+   - `Home → Find & Select → Go To Special → Visible cells only` highlights what's visible. Compare to the configured Delete Range target: any hidden rows inside the range fall victim to the deletion silently.
+   - For a workflow that builds the `Range` expression dynamically from a row count (`UsedRange.Rows.Count`), confirm whether the count includes hidden rows. The COM `UsedRange.Rows.Count` includes hidden rows; the modern OpenXML enumeration does not — provider-dependent skew.
+
+The root cause must name **which of the five surfaces** the failure maps to, with the specific evidence: the exception text and class, the activity configuration (scope, `Range`, `ShiftCells`, `ShiftOption`), and the workbook state (locked / filtered / structured Tables / merged regions). A generic "Delete Range failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Activity outside a scope container:**
+  - Wrap the Delete Range activity in the correct scope. Classic `Delete Range` → place inside `Excel Application Scope` with the workbook configured on the scope. Modern `Delete Range` (`DeleteRangeX`) → place inside `Use Excel File` with the workbook configured on the scope.
+  - Do not mix surfaces — a Classic Delete Range inside a Modern `Use Excel File` won't work, and vice versa. The toolbox shows them as separate entries; pick the one that matches the surrounding container.
+  - Prevention: when refactoring workflows, do not delete an `Excel Application Scope` or `Use Excel File` container without auditing every Excel activity nested inside. Studio's design-time validation catches the resulting orphans, but only if validation is enabled and the file is reopened in Studio post-edit.
+
+- **Branch 2 — Invalid range syntax or empty Range:**
+  - Use standard A1 notation, quoted as a string literal in the activity property: `"A1:B10"` (rectangular block), `"A:E"` (entire columns), `"3:7"` (entire rows), `"A1"` (single cell). The sheet name goes in the separate `SheetName` property — never in `Range`.
+  - Never leave `Range` blank. Excel COM has no concept of "delete nothing"; an empty string is a configuration error, not a noop.
+  - For expression-based ranges: validate the resolved value before the activity. Add a `Log Message Level=Info Message=$"Range: '{range}'"` immediately before Delete Range. If the resolved value can be empty under any input, guard the activity with an `If` that skips the delete when the range is empty / invalid, or fix the expression so it never produces an invalid range.
+  - For `lastRow`-style expressions: compute `lastRow` defensively. `If lastRow <= 0 Then` → skip; otherwise `Range = "A1:B" & lastRow.ToString`.
+  - Prevention: prefer literal ranges where the deletion target is known at design time. Expression-based ranges are a runtime hazard that benefits from explicit validation.
+
+- **Branch 3 — ShiftCells / ShiftOption conflict:**
+  - **If the intent is to clear data while preserving cell layout / formatting**: set `ShiftCells` to False, OR replace Delete Range with `Clear Range`. Clear Range wipes cell values without affecting the surrounding sheet structure; it does not require a shift direction and does not interact with merged cells or structured Tables.
+  - **If the intent is to remove cells and reflow surrounding data**: ensure `ShiftOption` matches the range shape and surrounding structure. `ShiftUp` requires that the rows below the range are not part of a merged region that crosses the deletion boundary. `EntireRow` deletes whole rows — preferred when the range spans full rows anyway, since Excel handles whole-row deletion more robustly than partial-row shifts.
+  - **If the range intersects an Excel Table** (`Ctrl+T` structured range): use the table's own row-delete semantics rather than Delete Range. Workflow option: convert the table to a normal range (`Table Tools → Convert to Range`) before the deletion, then re-apply the table after, OR refactor to use a `Filter Range` followed by manual row removal.
+  - Reproduce the operation manually in Excel to confirm the fix: open the workbook, select the configured range, `Home → Delete → Delete Cells…`, pick the same shift direction. If Excel performs the deletion cleanly, the activity will too.
+  - Prevention: avoid `ShiftCells: True` on workbooks with structured Tables or merged regions adjacent to deletion targets. Use `EntireRow` deletes when the workflow's intent is row removal; the activity is more predictable than partial-row shifts.
+
+- **Branch 4 — 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 (Delete 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 `Read-only mode` is False on the scope. Default-True is a footgun that converts every write — including Delete Range — into a silent no-op or a confusing read-only-violation error.
+
+- **Branch 5 — Range misalignment over filtered data:**
+  - Remove the active filter before Delete Range. Insert a `Remove Data Filter` (Modern) or `Filter Range` with `Action: Remove` (Classic) before the Delete Range activity, targeting the same sheet. After the deletion, re-apply the filter if downstream activities expect it.
+  - Alternative: have the workflow operate on filter-aware row identifiers (e.g., a key column) instead of cell coordinates. Read the filtered DataTable, identify rows by key, then delete rows by reapplying the filter and using `Delete Row` on individual matches — slower but correct under filtered conditions.
+  - For workflows that compute the `Range` from a `UsedRange.Rows.Count`: be aware that this count is provider-dependent. The Modern OpenXML enumeration may differ from the Classic COM count when hidden rows are present. Validate the resolved range against the workbook's visible state before relying on it.
+  - Prevention: workflows that mutate filtered workbooks should explicitly handle the filter state — either remove the filter before any range mutation, or operate on a filter-aware abstraction (DataTable + key matching) that doesn't depend on cell coordinates lining up.
+
+## Anti-patterns (what NOT to do)
+
+Common advice for Delete 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 Delete Range."** A `Delay` is a workaround for a race condition or initialization issue that the workflow author has not actually diagnosed. For Delete Range, the most common temptation is to add a Delay after opening the workbook (branch 4) or after a preceding filter operation (branch 5). The Delay "works" intermittently — it papers over branch 4 (the file lock from a prior orphan that happens to release within the delay window) or branch 5 (Excel's filter-change settling that COM exposes asynchronously). A reliable fix names the specific timing dependency: kill orphan EXCEL.EXE explicitly before the activity (branch 4 stop-gap), or remove the filter explicitly via the corresponding activity (branch 5). If a `Delay` is genuinely required, treat it as a diagnosis hint, document the dependency in a comment, and pick a duration an order of magnitude above the worst observed case.
+
+- **"Wrap Delete Range in a Try Catch and continue on error."** A bare Try-Catch that catches `ArgumentException` / `COMException` / `System.Exception` and only logs without re-throwing turns Delete Range failures into silent skips — the workflow proceeds as if the deletion succeeded, leaving stale rows in the workbook. Downstream Read Range activities then process those stale rows as if they were new data, producing wrong outputs that are far harder to diagnose than the original exception. Use Try-Catch only with a real recovery path: fall back to `Clear Range` for branch 3, mark the queue item Failed for branch 4, send a notification, or re-throw a domain-specific exception.
+
+- **"Use Delete Range when you only need to clear data."** Delete Range removes cells and (when `ShiftCells: True`) reflows surrounding data; `Clear Range` removes cell values while preserving cell layout, formatting, and surrounding structure. Workflows that only need to wipe values before a fresh Write Range should use Clear Range. Using Delete Range "because it sounded similar" is a category error that surfaces as branch 3 (shift conflicts) or branch 5 (misalignments) — the underlying bug is the wrong activity choice, not a configuration issue.
+
+## Prevention (cross-branch)
+
+- Confirm at design time that every `Delete Range` activity has an enclosing `Excel Application Scope` (Classic) or `Use Excel File` (Modern). Studio's validation catches the orphan case; do not suppress validation warnings on Excel activities.
+- Use literal A1 ranges where the deletion target is known at design time. Expression-based ranges require explicit runtime validation (logging + skip-on-empty guards).
+- Set `ShiftCells: False` unless the workflow specifically needs to reflow surrounding cells. The default-True is a frequent source of branch 3 failures on workbooks with structured Tables or merged regions.
+- Use `Clear Range` instead of Delete Range when the intent is to wipe cell values without changing the sheet's structure. The activity is purpose-built for that case and avoids the shift / filter / table-intersection failure modes.
+- For workflows that operate on filtered workbooks: explicitly remove the filter before any range mutation, then re-apply it after. Do not rely on Delete Range to handle filtered ranges correctly — it operates on coordinates, not visible rows.
+- Provision Robot hosts with predictable Excel state — no `Personal.xlsb` interfering, no leftover orphan `EXCEL.EXE` from prior jobs (kill at job start as a hygiene step, not as a fix for branch 4), and write permissions on the workbook's containing folder for the Robot user.
+
+## 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. Branches 4 (file lock) and the sheet-name pivot in step 2 inherit the diagnostic chains from those playbooks.
+- [`../overview.md`](../overview.md) — package overview, including the scope-container model that branch 1 violates.
+- For headless workflows where the deletion target is best expressed in code rather than cell coordinates, consider migrating the relevant logic to UiPath Data Manipulation activities (`Filter DataTable` / `Remove Data Row` / `For Each Row in DataTable`) operating on a `Read Range` result, then writing the modified `DataTable` back via `Write Range`. The DataTable round-trip avoids the in-place deletion failure modes entirely.

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

@@ -0,0 +1,139 @@
+---
+confidence: medium
+---
+
+# Use Excel File / Excel Application Card Failures
+
+## Context
+
+The Modern `Use Excel File` activity (class `UiPath.Excel.Activities.ExcelApplicationCard`, also surfaced as "Excel App Card" in some contexts) and the Classic `Excel Application Scope` are the scope containers that govern an Excel workbook's lifecycle for child activities (Read Range, Write Cell, Append Range, etc.). The card / scope acquires the workbook, manages the underlying provider (OpenXML by default for Modern; Excel COM for Classic and for Modern when COM-forcing properties are set), and releases the file when its body completes.
+
+Failures originate at one of five surfaces: provider acquisition (Excel COM unavailable when needed), workbook-path resolution (the configured path is empty, null, or contains illegal characters), Excel-process lifecycle (multiple cards collide on the EXCEL.EXE process without an `Excel Process Scope` to govern them), child-activity placement (a Modern Excel child activity dropped outside any card), or sensitivity-label rejection (Microsoft Purview / AIP-protected workbooks under package versions before the sensitivity-label properties were added).
+
+What this looks like — Use Excel File / Excel Application Card faults surface as one of these signatures:
+
+- `UiPath.Excel.BusinessException: Error opening workbook. Make sure Excel is installed.` (or near-identical wording) — the card / scope needs Excel COM but the host has no Excel install, or the install is broken / unrepaired. Branch 1.
+- `System.ArgumentException: Excel File path is empty or not set` / `System.ArgumentException: Illegal characters in path '<path>'` / `System.IO.FileNotFoundException` from the path-binding step — the configured `WorkbookPath` property evaluates to empty, null, whitespace, or a malformed string. Branch 2.
+- `System.Runtime.InteropServices.COMException` with `RPC_E_SERVER_UNAVAILABLE` (`0x800706BA`), `RPC_E_DISCONNECTED` (`0x80010108`), or `CO_E_SERVER_EXEC_FAILURE` (`0x80080005`) — multiple scopes raced on the same EXCEL.EXE process, OR a prior scope tore down the process and a follow-up scope tries to attach. Branch 3.
+- `UiPath.Excel.BusinessException` mentioning "must be placed inside" / "missing parent container" — a Modern Excel CHILD activity (Read Range, Write Cell, etc.) was dropped outside any `Use Excel File` / `Excel Application Scope`. Branch 4 (cross-cut).
+- `System.Runtime.InteropServices.COMException` or `UiPath.Excel.BusinessException` referencing "sensitivity label", "information protection", or "label is required" — the workbook is protected under a Microsoft Purview / Azure Information Protection (AIP) sensitivity policy and the card doesn't supply the required label / operation properties. Branch 5.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Excel not installed / Interop unavailable** — the card / scope decided it needs Excel COM (because the Classic scope is COM-only, OR because a Modern card has a COM-forcing property like `Read Formatting`, OR the file extension is `.xls`/`.xlsb` requiring COM). The host has no Excel installed, OR Excel's COM registration is broken from a botched install / repair / Office 2024 click-to-run upgrade. The activity throws `BusinessException: Error opening workbook. Make sure Excel is installed.` before any file open.
+2. **Empty / invalid / illegal WorkbookPath** — the `WorkbookPath` property is bound to a variable / expression that evaluates to null, empty string, whitespace-only, OR contains characters illegal in Windows file paths (control chars, NUL, asterisks in mid-path, mixed `/` and `\` separators in some package versions). Common causes: variable declared in an inner scope so the card sees it as `Nothing`; preceding `Read Cell` returned empty; `String.Format` against a `Nothing` produced an empty literal; a config file lookup failed silently.
+3. **COM / RPC failures across scopes (race condition or torn-down process)** — common scenarios: two `Use Excel File` cards in sequence against the same path with no `Excel Process Scope` wrapping them (the first card closes EXCEL.EXE; the second tries to attach to a process that no longer exists); parallel branches both opening the same path; a child `Execute Macro` activity called `Application.Quit` from VBA (see also `execute-macro-failures.md` branch 3 for the macro-tears-down-Excel chain). The Modern `Use Excel File` is generally OpenXML by default and avoids this; the failure mode is concentrated on Classic `Excel Application Scope` and Modern cards with COM-forcing properties.
+4. **Modern Excel child activity outside any card / scope** — a Read Range, Write Cell, Append Range, Delete Range, Execute Macro, etc. sits at the workflow root without a `Use Excel File` (Modern) or `Excel Application Scope` (Classic) wrapping it. The child activity throws `BusinessException: <activity> must be placed inside a 'Use Excel File' container`. This is a child-activity failure surface — see the individual activity playbooks (`append-range-failures.md`, `delete-range-failures.md`, etc.) for the per-activity diagnostic chain; this playbook's branch 4 is a brief cross-cut.
+5. **Sensitivity label rejection (Microsoft Purview / AIP)** — the workbook has a sensitivity label applied (e.g., "Confidential", "Highly Confidential", "Internal Use Only") under Microsoft Purview / Azure Information Protection. The Excel card opens the file but cannot write to it without supplying the appropriate `SensitivityLabel` / `SensitivityOperation` properties (introduced in `UiPath.Excel.Activities` v2.23.4+). On pre-v2.23.4 packages the card has no way to supply the label; on v2.23.4+ the failure means the workflow needs to set the properties explicitly.
+
+What to look for:
+
+- **The exception class and message** — first signal. `BusinessException: Error opening workbook` → branch 1. `ArgumentException: path is empty` / `Illegal characters in path` → branch 2. `COMException RPC_E_*` / `0x800706BA` / `0x80010108` / `0x80080005` → branch 3. `BusinessException: must be placed inside` (on a child activity, NOT the card itself) → branch 4. `COMException` / `BusinessException` mentioning sensitivity / label / information protection → branch 5.
+- **Workflow source** — which surface is in use (Modern `Use Excel File` / Classic `Excel Application Scope`), the configured `WorkbookPath` (literal vs. expression), the `ReadOnly` property, any COM-forcing properties (`Read Formatting`, `Edit Password`, `Visible`), and whether the workflow has multiple Excel scopes in sequence or parallel.
+- **Host's Excel install state** — is Excel installed on the Robot host? Which version (2016, 2019, 2021, M365 click-to-run)? Has the install been repaired recently? Is there a known-good `excel.exe` at `C:\Program Files\Microsoft Office\root\Office16\excel.exe` (or equivalent)? Relevant to branch 1.
+- **The `WorkbookPath`'s runtime value** — what does the variable / expression resolve to immediately before the card? Log it with `Log Message Level=Info Message=$"WorkbookPath: '{path}' (length={path.Length})"` — empty, whitespace, illegal characters all become visible.
+- **Excel Process Scope presence** — if the workflow has multiple `Use Excel File` cards in sequence (or in a loop), is there an outer `Excel Process Scope` wrapping the whole sequence? Without it, each card opens/closes EXCEL.EXE independently and races. Relevant to branch 3.
+- **Package version** — `UiPath.Excel.Activities` version from `project.json`. Branch 5 is gated at v2.23.4 (the SensitivityLabel properties weren't available before that).
+- **Workbook protection state** — does the workbook have a sensitivity label applied? Open it in Excel and look for the label badge in the title bar / status bar (typically "Sensitivity: Confidential" or similar). Relevant to branch 5.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, activity surface, and configuration.** From `uip or jobs get <job-key> --output json` → `Info`: exception class, full message, HRESULT, inner exception. From workflow source: which Excel scope surface (Modern card vs. Classic scope), the configured `WorkbookPath`, `ReadOnly`, any COM-forcing properties, whether multiple scopes exist in sequence / parallel, and whether an `Excel Process Scope` wraps them. From `project.json`: the `UiPath.Excel.Activities` version. From job logs: any `Log Message` lines capturing the `WorkbookPath` value before the scope.
+
+2. **Branch the diagnostic on the exception signature.**
+   - `BusinessException: Error opening workbook. Make sure Excel is installed.` → branch 1; go to step 3.
+   - `ArgumentException` referencing "path is empty" / "Illegal characters in path" → branch 2; go to step 4.
+   - `COMException` with `RPC_E_SERVER_UNAVAILABLE` / `RPC_E_DISCONNECTED` / `CO_E_SERVER_EXEC_FAILURE` HRESULTs → branch 3; go to step 5.
+   - `BusinessException` on a CHILD activity referencing "must be placed inside a Use Excel File / Excel Application Scope" → branch 4; pivot to the per-activity sibling playbook (see [`../summary.md`](../summary.md)).
+   - `COMException` / `BusinessException` referencing "sensitivity label" / "information protection" / "label is required" → branch 5; go to step 6.
+
+3. **Confirm branch 1 (Excel not installed / Interop unavailable).** Check:
+   - **Is the scope a Classic `Excel Application Scope`?** Classic is COM-only — it ALWAYS needs Excel installed. If yes, branch 1 is plausible; verify by checking the host.
+   - **Is the scope a Modern `Use Excel File` with COM-forcing properties?** Modern defaults to OpenXML but falls back to COM when `Read Formatting`, `Edit Password`, certain `Visible`/`Auto Save` combinations, or `.xls`/`.xlsb` file extensions are in play. Inspect the card's properties — any COM-forcing flag means Excel must be installed.
+   - **Is Excel actually installed on the Robot host?** Confirm via the host's `Get-ItemProperty 'HKLM:\Software\Microsoft\Office\*\Excel\InstallRoot'` (PowerShell) or by checking that `excel.exe` exists at the expected path. If absent, branch 1 is confirmed.
+   - **Is the install broken?** Check if Excel can be launched interactively on the host. A working install opens with no error dialog; a broken install shows registration errors, missing-DLL warnings, or recovery prompts. UiPath's "Repair Tool for Microsoft Office" (Studio → Tools tab) and Office's Online Repair are the canonical fixes.
+
+4. **Confirm branch 2 (empty / illegal WorkbookPath).** Inspect the workflow source. The `WorkbookPath` property is either a literal (rare for branch 2) or an expression. For expression cases:
+   - Trace the expression's source variable backward. If it's an `Assign`, did the assignment run in this execution path? If it's an `Out Argument` from an invoked workflow / sub-workflow, did the producer return a non-empty value?
+   - Add a `Log Message Level=Info Message=$"WorkbookPath resolved to: '{path}' (length={path.Length}, IsNothing={path Is Nothing})"` immediately before the card and re-run. The log makes the resolved value visible.
+   - Check for illegal characters: control chars (NUL, BEL, etc.), embedded newlines (from a config-file read that didn't trim), mixed `\` and `/` separators, mid-path asterisks / question marks, leading/trailing whitespace, unbalanced quotes. The `System.IO.Path.GetInvalidPathChars()` API enumerates the strict illegal-char set.
+   - For UNC paths: confirm the share is reachable from the Robot host's session (mapped drive letters from interactive sessions don't auto-map under a Robot session).
+
+5. **Confirm branch 3 (COM/RPC across scopes).** Check:
+   - **Multiple sequential `Use Excel File` cards or `Excel Application Scope` blocks?** Look at the workflow source for two or more Excel-scope activities in the same Sequence. Are they wrapped by an `Excel Process Scope` (Modern, outermost)?
+   - **Parallel Excel access?** Look for `Parallel` activities containing Excel scopes against the same file path. Excel COM is single-threaded apartment (STA); parallel access is a hard violation.
+   - **Macro tearing down Excel?** If a child `Execute Macro` ran VBA that called `Application.Quit` / `Workbooks.Close`, the NEXT card / scope sees an `RPC_E_DISCONNECTED` because its workbook reference points at a process that no longer exists. Cross-cut to [`./execute-macro-failures.md`](./execute-macro-failures.md) branch 3 for the macro-side diagnostic.
+   - **Multi-Robot host?** Multiple Robot jobs concurrently invoking Excel COM on the same host hit the STA apartment from different threads. Failures are intermittent (race-dependent).
+
+6. **Confirm branch 5 (sensitivity label rejection).** Check:
+   - **Package version**: read `UiPath.Excel.Activities` from `project.json`. If < 2.23.4, the SensitivityLabel / SensitivityOperation properties don't exist in the card. The fix requires a package upgrade. If ≥ 2.23.4, continue.
+   - **Workbook protection state**: open the target workbook in Excel on a developer host. Look for the sensitivity badge in the title bar (e.g., "Sensitivity: Confidential — UiPath Internal"). If absent, the failure isn't branch 5; recheck against the other branches.
+   - **The card's `SensitivityLabel` / `SensitivityOperation` properties**: are they configured on the failing card? If left empty AND the workbook has a label that requires programmatic acknowledgement, the write fails. The fix is to set the properties to match the workbook's label.
+
+The root cause is **which of the five surfaces** the failure maps to. A confirmed finding names the surface (Modern card / Classic scope), the resolved `WorkbookPath` value (for branch 2), the host's Excel install state (for branch 1), the scope-nesting topology (for branch 3), or the workbook's sensitivity label state (for branch 5).
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Excel not installed / Interop unavailable:**
+  - **Repair Tool path**: from UiPath Studio → Tools → "Repair Tool for Microsoft Office". This is the lightweight first attempt; it re-registers the Excel COM components without a full Office reinstall. Quick to try.
+  - **Office Online Repair**: Windows Control Panel → Programs and Features → Microsoft Office → Change → Online Repair. Heavier, addresses registry corruption from interrupted installs / upgrades. Requires admin rights on the Robot host.
+  - **No Excel on the host at all** (headless / unattended deployment): migrate the workflow to Workbook activities (`Read Range Workbook`, `Write Range Workbook`, `Append Range Workbook`, etc.) which don't require Excel installed. Or replace the Modern `Use Excel File` card with one that doesn't force COM (remove COM-forcing properties like `Read Formatting`, switch `.xls` files to `.xlsx`).
+  - For Modern `Use Excel File` cards that fell back to COM unintentionally: audit the card's properties and remove the COM-forcing flag if the workflow doesn't actually need Excel features. The card will then use OpenXML and not require Excel.
+
+- **Branch 2 — Empty / invalid / illegal WorkbookPath:**
+  - **Empty / null variable**: trace the variable's source upstream. If the producer can legitimately return empty (e.g., a config-file read where the key is missing), guard the card with `If` checking `Not String.IsNullOrWhiteSpace(workbookPath)`. Skip the card or log/throw a clear error in the false branch.
+  - **Variable scope drift**: move the variable declaration to the parent scope of the card so the card sees the assignment. Or initialize the variable at declaration to a known-default value.
+  - **Illegal characters**: sanitize the path before passing to the card. Strip control chars with `Regex.Replace(path, "[\x00-\x1F]", "")`. Trim whitespace with `path.Trim()`. Normalize separators with `path.Replace("/", "\\")`. Validate against `Path.GetInvalidPathChars()` and abort with a clear error if any remain.
+  - **For paths built from string interpolation**: log the resolved value before the card to confirm the expression evaluates as expected. A `Log Message` of the full resolved path is the cheapest debugging insurance.
+  - **For UNC paths**: confirm the Robot user has access to the share. Test with `Test-Path` PowerShell on the Robot host; if it fails, the share isn't reachable from the Robot's session and the path string is irrelevant (the file open will fail regardless).
+
+- **Branch 3 — COM / RPC failures across scopes:**
+  - **Wrap multiple sequential Excel scopes in an `Excel Process Scope`** (Modern, outermost). The Process Scope is the recommended pattern for any workflow with more than one `Use Excel File` against the same or different paths in sequence. It governs the EXCEL.EXE lifecycle across the inner scopes, so the second card doesn't try to attach to a dead process.
+  - **Avoid `Parallel` activities containing Excel scopes against the same file** — STA apartment is single-threaded; the parallel design is incompatible. Restructure to sequential.
+  - **For macro-tears-down-Excel**: see `execute-macro-failures.md` branch 3. Remove `Application.Quit` / `Workbooks.Close` from the VBA so UiPath owns the lifecycle.
+  - **For multi-Robot host concurrency**: serialize Excel access at the orchestration layer (single-performer queue, per-host lock asset) so only one job per host has Excel COM open at a time.
+  - **Stop-gap, NOT a fix**: add a `Retry Scope` around the failing card with exponential back-off (3 attempts, 5s/15s/30s). RPC errors are sometimes transient; a retry can mask intermittent races. Treat this as a diagnostic patch — the underlying race condition is still there.
+
+- **Branch 4 — Modern Excel child activity outside any card / scope:**
+  - This is the per-activity failure surface — see the individual activity playbooks for the per-activity diagnostic and fix chain (e.g., [`./append-range-failures.md`](./append-range-failures.md) branch 1, [`./delete-range-failures.md`](./delete-range-failures.md) branch 1, etc.). The card's playbook briefly mentions this branch because the user's first hypothesis is often "the card is failing" when in fact the child activity is failing because the card was removed or never present.
+  - General fix: wrap the failing child activity in the appropriate scope (Modern `Use Excel File` for Modern activities; Classic `Excel Application Scope` for Classic activities).
+
+- **Branch 5 — Sensitivity label rejection:**
+  - **Upgrade `UiPath.Excel.Activities` to v2.23.4 or newer** if currently on an older version. The SensitivityLabel and SensitivityOperation properties are required to write to AIP-protected workbooks.
+  - **Configure the card's `SensitivityLabel` property** to match the target workbook's label name (e.g., `"Confidential - UiPath Internal"`). The exact label string must match the Microsoft Purview / AIP policy's label name verbatim.
+  - **Set `SensitivityOperation`** to the appropriate operation (`Keep` to preserve the label, `Apply` to set/change it, `Remove` to clear it — naming may vary by package version).
+  - **Verify the Robot user has the AIP rights** to operate on the label. Microsoft Purview enforces label-level user / group permissions; if the Robot user isn't in the label's allowed list, the operation will fail with a different error (auth-related) at the AIP layer.
+  - **For workbooks where label management isn't part of the workflow's intent**: use `Keep` to pass through the label unchanged. The workflow reads / writes data; the label stays.
+
+## Anti-patterns (what NOT to do)
+
+Common advice for Use Excel File / Excel Application Card 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` before the Use Excel File card."** A Delay is a workaround for a race condition the workflow author hasn't diagnosed. For branch 3 (COM/RPC across scopes), the Delay sometimes works because the prior EXCEL.EXE finally terminates within the delay window — but the underlying race is still there. A reliable fix is wrapping the scopes in an `Excel Process Scope` to govern the EXCEL.EXE lifecycle. If a Delay seems to "fix" the issue, treat it as a diagnostic hint that there's a real race condition to address.
+
+- **"Wrap the Use Excel File card 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 scope failures into silent skips — the child activities inside the catch don't run, and the workflow proceeds with stale or missing data. For branch 1 (Excel not installed), the catch hides the configuration issue; for branch 3 (COM/RPC), it hides the race; for branch 5 (sensitivity label), it hides the access denial. Use Try-Catch only with a real recovery path (retry with cleaned config, notify ops, fall back to Workbook activities, etc.).
+
+- **"Set `Visible: True` on the card to 'see what's happening'."** For unattended Robots, `Visible: True` makes the Excel UI appear on the desktop session — but in many unattended sessions the desktop isn't rendered, so the property has no effect. Worse, for headless / no-Excel deployments, `Visible: True` is a COM-forcing property that turns a Modern OpenXML workflow into a Modern COM workflow — making branch 1 (Excel not installed) failures appear where they didn't before. Don't set `Visible: True` unless you specifically need to interact with the Excel UI from the workflow.
+
+- **"Downgrade `UiPath.Excel.Activities` to silence the sensitivity-label error."** Branch 5's error was added because pre-v2.23.4 packages had no way to handle AIP-protected workbooks correctly — the workflow would either silently produce wrong data OR throw a confusing AIP-side error elsewhere. The explicit SensitivityLabel properties are the FIX, not the symptom. Downgrading the package reintroduces the original problem.
+
+## Prevention (cross-branch)
+
+- For workflows with multiple `Use Excel File` cards in sequence (or in a loop), default to wrapping them in an `Excel Process Scope`. The Process Scope is cheap (no per-iteration cost when there's only one card) and prevents the branch 3 race conditions when the workflow grows.
+- For Robot hosts without Excel installed, audit all `Use Excel File` cards for COM-forcing properties (`Read Formatting`, `Edit Password`, `Visible`, certain Auto Save combinations). Remove the COM-forcing flags if the workflow doesn't need Excel features, OR migrate the workflow to Workbook activities entirely.
+- For workflows whose `WorkbookPath` is dynamic (from config, scraping, queue payload, etc.), validate the resolved path with a guard activity (`If Not String.IsNullOrWhiteSpace(path) AndAlso File.Exists(path) Then ...`) before the card. The validation is cheap; the alternative is debugging an opaque path error later.
+- For workbooks under enterprise sensitivity-label policies, pin `UiPath.Excel.Activities` to v2.23.4 or newer in `project.json`. Document the sensitivity-label requirement in the workflow comments so future contributors don't accidentally downgrade.
+- Avoid `Parallel` activities containing Excel scopes. STA apartment is a hard constraint; design around it with sequential or queue-serialized access.
+- When refactoring a workflow that removes a `Use Excel File` card, audit every nested Excel activity to ensure the scope removal didn't orphan any of them (branch 4 cross-cut).
+
+## Related
+
+- Other Excel Activities failure fingerprints (per-child-activity playbooks) are separate; see [`../summary.md`](../summary.md) for navigation. Branch 4 (child activity outside any card) pivots to the corresponding per-activity playbook (`append-range-failures.md`, `delete-range-failures.md`, `execute-macro-failures.md`, etc.).
+- [`./execute-macro-failures.md`](./execute-macro-failures.md) — branch 3's cross-cut on macros tearing down Excel via `Application.Quit` / `Workbooks.Close`. The card-side and macro-side symptoms are linked; fixing one without the other leaves the workflow brittle.
+- [`./delete-range-failures.md`](./delete-range-failures.md) — sibling range-mutation playbook; branch 4 of this playbook cross-cuts that playbook's branch 1.
+- [`../overview.md`](../overview.md) — package overview, including the scope-container model and the OpenXML-vs-COM provider distinction load-bearing for branches 1 and 3.
+- For headless workflows that can't (or shouldn't) require Excel installed: consider migrating Excel automation to the cloud surface via `o365-activities/` (Microsoft Graph API). That surface has no Excel COM dependency and avoids branches 1, 3, and 5's COM-side failures entirely. Sensitivity labels are still respected via the Graph API but through a different property model.