@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/invoke-vba-com-interop-failure.md

@@ -0,0 +1,49 @@
+---
+confidence: medium
+---
+
+# Invoke VBA — COM Interop Failure (0x80010100 and related HRESULTs)
+
+## Context
+
+What this looks like:
+- Activity `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) — or another activity inside the surrounding `Excel Process Scope` — faults with an HRESULT from the COM layer
+- Error message contains one of:
+  - `The system call failed. (Exception from HRESULT: 0x80010100 (RPC_E_SYS_CALL_FAILED))`
+  - `Call was rejected by callee. (Exception from HRESULT: 0x80010001 (RPC_E_CALL_REJECTED))`
+  - `The message filter indicated that the application is busy. (Exception from HRESULT: 0x8001010A (RPC_E_SERVERCALL_RETRYLATER))`
+  - `Retrieving the COM class factory for component with CLSID {...} failed due to the following error: 80080005`
+  - `The remote procedure call failed. (Exception from HRESULT: 0x800706BE)`
+- Failures are often intermittent — the same workflow succeeds on one run and faults on the next
+- The job may have been running for some time before this activity faulted (Excel was in a degraded state before the macro tried to execute)
+
+What can cause it (more than one may apply):
+- **Excel busy with a modal dialog** — Excel.exe is foregrounded on a license activation prompt, a "recover unsaved files" banner, a macro-warning bar, a "trust this file" prompt, or a "this file came from the internet" Protected View bar. COM calls into Excel are blocked until the dialog is dismissed. If `Excel Process Scope` was opened with `Visible = False` (the default for unattended), the dialog is invisible to whoever is watching the robot but still blocks the macro.
+- **Excel.exe hung or unresponsive** — a previous run left Excel.exe orphaned (e.g., the workflow crashed without closing the scope), and the new run's COM call lands on the wedged process.
+- **Multiple Office versions installed** — the host has both Microsoft 365 Apps and a perpetual Office install (2016/2019/2021), or both click-to-run and MSI installs. The COM dispatcher cannot deterministically resolve which Excel is the target, leading to intermittent `0x80010100` / `0x80080005` errors.
+- **Bitness mismatch** — the installed Office is 32-bit but the robot process is 64-bit (or vice versa). COM interop will sometimes succeed (in-proc translation) and sometimes fault (cross-bitness marshaling), depending on which APIs the activity hits.
+- **Resource contention on the host** — Excel was launched concurrently by a user, another robot, or a scheduled task while the macro was running, causing the COM server to drop the active call.
+
+## Investigation
+
+1. Read the error message and HRESULT code from job evidence. Capture the exact HRESULT — `0x80010100`, `0x80010001`, etc. — and the activity that faulted.
+2. Confirm the faulted activity is inside an `Excel Process Scope` and read the scope's `Visible` property from the workflow `.xaml`. If `Visible = False`, modal dialogs are invisible during the run.
+3. Ask the user (or someone with desktop access to the robot machine, signed in as the robot's Windows user) to:
+   - Re-run the workflow with the `Excel Process Scope`'s `Visible` set to `True`.
+   - Observe Excel during the run. Note any dialog, banner, or prompt that appears: license activation, recover unsaved files, macro warning, Protected View, file lock notice, trust-this-file prompt.
+4. Check the robot machine for orphaned Excel processes before the next run (Task Manager → look for `EXCEL.EXE` instances with no visible window).
+5. Capture the Office installation inventory on the robot machine: number of Office installs, edition (Microsoft 365 / Office 2019 / Office 2021), install channel (click-to-run vs. MSI), and bitness (32-bit vs. 64-bit). The bitness is shown under `File > Account > About Excel`.
+
+## Resolution
+
+- **If a modal dialog was blocking** — dismiss the dialog source before the macro runs. Options:
+  - **Recover unsaved files / yellow Protected View bar:** open the workbook once interactively on the robot machine, dismiss the prompt, save and close cleanly so the recovery state is cleared.
+  - **License activation prompt:** complete Office activation on the robot machine under the Windows user the robot runs as.
+  - **Macro-warning bar / "trust this file" prompt:** add the workbook's folder to Excel Trusted Locations (`File > Options > Trust Center > Trust Center Settings > Trusted Locations`), or sign the macro with a certificate the host trusts.
+  - **File from the internet / Mark-of-the-Web:** unblock the file (`Right-click > Properties > Unblock`) or pre-process it with `Unblock-File <path>` in PowerShell before the workflow runs.
+- **If Excel.exe was orphaned from a previous run** — wrap every Excel automation in an `Excel Process Scope` (so the scope's `Dispose` always closes Excel) and ensure no `Try/Catch` swallows the scope's exit. As a one-time cleanup, kill orphaned `EXCEL.EXE` processes on the robot machine via Task Manager or `Stop-Process -Name EXCEL -Force`.
+- **If multiple Office versions are installed** — uninstall the redundant Office install (typically the older perpetual edition, leaving Microsoft 365 Apps). Two coexisting Office installs are unsupported by Microsoft for COM automation and will continue to produce intermittent errors until consolidated.
+- **If Office bitness does not match the robot process bitness** — reinstall Office at the same bitness as the robot (preferred: 64-bit Office for 64-bit robots), or run the robot under the matching bitness. Mixed bitness is supported by Office in general but is a known source of COM-interop instability for `Invoke VBA`.
+- **If the host has concurrent Excel use** — schedule the workflow off-hours, dedicate the robot machine to unattended execution, or use a different host where Excel will not be opened interactively during the run.
+
+If the HRESULT persists after all environmental causes are ruled out, capture a full robot log (`Verbose` level) plus a Process Monitor trace of `EXCEL.EXE` during the failure and open a UiPath support case — the residual cases are package or Office-version-specific bugs that need vendor diagnosis.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/invoke-vba-entry-method-name.md

@@ -0,0 +1,36 @@
+---
+confidence: high
+---
+
+# Invoke VBA — Entry Method Name Mismatch
+
+## Context
+
+What this looks like:
+- Activity `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) faults at the moment it calls `Application.Run("<EntryMethodName>", ...)`
+- Error message contains one of: `Cannot run the macro '<name>'. The macro may not be available in this workbook or all macros may be disabled`, `Sub or Function not defined`, or `The macro '<name>' cannot be found`
+- The code file at `CodeFilePath` exists, is well-formed VBA, and compiles — but the named entry point cannot be resolved
+
+What can cause it:
+- **Typo or whitespace** in `EntryMethodName` — the string passed to `Application.Run` does not match any declared `Sub`/`Function` in the injected module (extra trailing space, hyphen vs. underscore, missing letter).
+- **Parentheses appended** — `EntryMethodName` set to `MyMacro()` instead of `MyMacro`. `Application.Run` expects the bare identifier; the parentheses are interpreted as part of the name and fail to resolve.
+- **Case mismatch on legacy Excel builds** — VBA source is case-insensitive, but `Application.Run` on some older Excel builds has been observed to reject case-mismatched names. Modern Office matches case-insensitively, but the safest practice is to copy the name exactly from the code file.
+- **Macro is nested inside another `Sub`/`Function` or declared `Private`** — VBA only exposes top-level `Public` (or unmarked, which defaults to `Public` at module scope) procedures to `Application.Run`. A nested or `Private`-marked `Sub` is unreachable.
+- **Wrong code file loaded** — `CodeFilePath` points to a different file than the user expects (stale path, similarly-named file in a different folder), and the macro the user named genuinely doesn't exist in the loaded file.
+
+## Investigation
+
+1. Read the `InvokeVBAX` node from the workflow `.xaml` and capture the literal `EntryMethodName` value, with any trailing whitespace.
+2. Open the file at `CodeFilePath` and find every `Sub` and `Function` declaration. Capture each declared name and its scope keyword (`Public`, `Private`, or unmarked).
+3. Compare `EntryMethodName` to the declared names. Check:
+   - Exact character match (no extra spaces, no trailing `()`, no zero-width characters).
+   - Whether the matching declaration is `Private` or nested inside another procedure.
+4. If multiple `.txt`/`.vba` files exist under the project, confirm `CodeFilePath` resolves to the file the user intends — not a similarly-named one.
+
+## Resolution
+
+- **If `EntryMethodName` has trailing parentheses** — remove them. Set the property to the bare identifier (e.g., `MyMacro`, not `MyMacro()`).
+- **If `EntryMethodName` has a typo or whitespace mismatch** — fix the property to match the declared `Sub`/`Function` name exactly, character for character.
+- **If the matching declaration is `Private` or nested** — edit the code file: make the target procedure top-level (move it out of the enclosing `Sub`/`Function`) and either mark it `Public` or remove the `Private` keyword. Save and re-run.
+- **If the declared name uses different casing than `EntryMethodName`** — fix `EntryMethodName` to match the case shown in the code file. This is defensive against older Excel builds even when the current build is case-insensitive.
+- **If the code file genuinely does not contain a `Sub`/`Function` with that name** — either add the missing procedure in the code file, or fix `CodeFilePath` to point at the file that does declare it.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/invoke-vba-parameter-formatting.md

@@ -0,0 +1,45 @@
+---
+confidence: medium
+---
+
+# Invoke VBA — Parameter Type or Shape Mismatch
+
+## Context
+
+What this looks like:
+- Activity `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) faults when marshaling `EntryMethodParameters` into the COM call
+- Error message contains one of: `Type mismatch`, `Wrong number of arguments or invalid property assignment`, `Unable to cast object of type ... to type ...`, or an `InvalidCastException` referencing `IEnumerable<Object>`
+- Alternative symptom: Studio freezes or crashes when the user types a parameter expression directly into the `EntryMethodParameters` field in the property panel
+- The code file compiles, `EntryMethodName` resolves correctly, but the macro never executes its first statement
+
+What can cause it:
+- **`EntryMethodParameters` not an `IEnumerable<Object>`** — the property is typed `IEnumerable<Object>` but the bound expression evaluates to a `String`, a single `Object`, or a strongly-typed array that does not implement the expected interface.
+- **Arity mismatch** — the array passed has more or fewer elements than the macro's `Sub`/`Function` signature accepts.
+- **Element type mismatch** — array elements are the wrong VBA type for the macro signature (e.g., a `String` passed to a `Sub TakesNumber(n As Long)`).
+- **Property-window inline typing** — typing a complex `New Object() {...}` expression directly into the `EntryMethodParameters` field in the property panel can freeze or crash Studio while it tries to re-parse on every keystroke. This is a Studio editor pathology, not a runtime error, but presents as the same activity failing to run.
+- **`Nothing` / `null` array** — `EntryMethodParameters` was never assigned, leaving the bound variable `null`. The activity passes `null` to `Application.Run`, which faults on the marshal.
+
+## Investigation
+
+1. Read the `InvokeVBAX` node from the workflow `.xaml` and capture the literal expression bound to `EntryMethodParameters`.
+2. Identify the type of that expression at the binding site (look at the declared type of the variable, or the type the expression evaluates to). Confirm it is `IEnumerable<Object>` or `Object[]`.
+3. Read the code file and capture the `Sub`/`Function` signature for `EntryMethodName` — parameter count and declared VBA types (`String`, `Long`, `Double`, `Variant`, `Boolean`, etc.).
+4. Compare:
+   - Parameter count in the array vs. parameter count in the signature.
+   - Element types in the array vs. declared VBA types.
+   - Whether any element is `Nothing`/`null` when the matching VBA parameter is not declared `Optional`.
+5. If the user reports Studio freezing or crashing during property edit (not at runtime), that is a distinct symptom — the property-window inline typing pathology.
+
+## Resolution
+
+- **If `EntryMethodParameters` is bound to a non-array value** — refactor to build an `Object` array via an `Assign` activity placed before `Invoke VBA`:
+  ```vb
+  ' Assign: macroParams = New Object() { param1, param2, param3 }
+  ```
+  Then bind `EntryMethodParameters` to `macroParams`.
+- **If arity is wrong** — match the array length to the macro signature exactly. If the macro takes no parameters, set `EntryMethodParameters` to `New Object() {}` (empty array) — not `Nothing`.
+- **If element types don't match** — cast each element to the matching VBA-compatible .NET type at the `Assign` site. `Long` ↔ `Int64`, `Integer` ↔ `Int32`, `Double` ↔ `Double`, `String` ↔ `String`, `Boolean` ↔ `Boolean`, `Variant` accepts any. Date values should be passed as `DateTime`.
+- **If `EntryMethodParameters` is `Nothing` because the variable was never assigned** — initialize the variable to `New Object() {}` (or the populated array) before `Invoke VBA` runs.
+- **If Studio froze during property edit** — close Studio, re-open the project, and build the parameter array via an `Assign` activity instead of typing the expression inline in the property panel. Bind the property field to the resulting variable name only. This avoids the per-keystroke re-parse pathology and is the documented authoring pattern for this property.
+
+If the parameter expression is correct and the macro still faults on the first statement, the failure is inside the macro itself — debug the VBA logic in Excel directly rather than continuing under this playbook.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/invoke-vba-trust-access.md

@@ -0,0 +1,38 @@
+---
+confidence: high
+---
+
+# Invoke VBA — Trust Access to VBA Project Denied
+
+## Context
+
+What this looks like:
+- Activity `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) faults the first time it tries to inject the macro module into the workbook
+- Error message contains one of: `Programmatic access to Visual Basic Project is not trusted`, `Programmatic access to Office VBA project is denied`, or a wrapped form referencing `VBProject`/`VBComponents.Add`
+- Job faults synchronously the moment `Invoke VBA` runs; the surrounding `Excel Process Scope` did not fault
+
+What can cause it:
+- Excel's "Trust access to the VBA project object model" setting is disabled on the robot machine, under the Windows user the robot runs as. `Invoke VBA` injects a new VBA module into the workbook via `Workbook.VBProject.VBComponents.Add` — that API call requires this setting to be enabled. This is the only cause — Excel returns the security block authoritatively before any macro source is read.
+
+Notes:
+- The setting is **per-user, per-machine, and per Office install**. Enabling it on a developer workstation does not propagate to the robot host; enabling it for one Windows user does not enable it for another.
+- The setting is not visible from Orchestrator, job logs, or trace evidence — confirmation requires desktop access to the robot machine under the correct user.
+
+## Investigation
+
+1. Read the activity stack/error from job evidence and confirm the faulted activity is `InvokeVBAX` and the message references trust, programmatic access, or `VBProject`.
+2. Confirm the `Excel Process Scope` around `Invoke VBA` opened successfully — if the scope itself faulted, this is a different problem (see the COM interop playbook).
+3. Ask the user (or someone with desktop access to the robot machine, signed in as the robot's Windows user) to check the Trust Center setting at:
+   `File > Options > Trust Center > Trust Center Settings... > Macro Settings > "Trust access to the VBA project object model"`.
+
+## Resolution
+
+- **If the setting is unchecked** — ask the user to enable it on the robot machine under the Windows user the robot runs as:
+  1. Open Microsoft Excel.
+  2. Go to `File > Options > Trust Center > Trust Center Settings...`.
+  3. Select `Macro Settings`.
+  4. Check `Trust access to the VBA project object model`.
+  5. Also check `Enable VBA macros` (or `Enable all macros` if the policy permits) so the injected macro is allowed to run.
+  6. Close all Excel windows so the setting takes effect on the next launch, then re-run the job.
+- **If the setting is checked but the error persists** — the setting is enforced per Office install and per Windows user. Verify (a) the same Windows user the robot runs as has the setting enabled (not just the interactive user who checked), and (b) the Excel version `Invoke VBA` is binding to is the same Office install where the setting was changed (see the COM interop playbook for multi-Office hosts). If still failing after both, treat this as a different cause and escalate.
+- **If Group Policy locks the setting** — the toggle is managed by the `VBAWarnings` / `AccessVBOM` registry policy and may be locked by a domain administrator. The user needs to work with IT to grant the exception for the robot machine; there is no workaround inside Studio.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/lookup-range-active-filters.md

@@ -0,0 +1,35 @@
+---
+confidence: medium
+---
+
+# Lookup Range — Value Not Found When Active Filters Exist
+
+## Context
+
+What this looks like:
+- Activity `Lookup Range` (`UiPath.Excel.Activities.ExcelLookUpRange` / `LookUpRangeX`) completes **without throwing** but returns a null, empty, or unexpected cell address
+- The value being searched for visibly exists in the spreadsheet when opened by hand, yet the lookup reports it is not present
+- Downstream activities then fault on the null/empty result (e.g. a later `NullReferenceException`, an empty-string write, or a wrong-row update) — the lookup itself logged no error
+
+What can cause it:
+- The target worksheet has **active AutoFilters or column filters** applied. When rows that contain the search value are hidden by a filter, `Lookup Range` does not see them and returns no match (or matches a different, visible row). This is a silent wrong-result, not an exception — the activity searches the *currently visible* cells, and filtered-out rows are excluded.
+
+Notes:
+- This is a **silent failure** — there is no error string in the job log from the activity itself. The symptom is a wrong/empty `Output` value, or a downstream fault that traces back to the lookup result. Do not expect a `Lookup Range` error line; look at what the activity *returned*.
+- A saved workbook can carry a filter state from a prior manual edit. The filter does not have to be applied by the workflow to bite.
+
+## Investigation
+
+1. Read the `Lookup Range` node from the workflow `.xaml`: capture the target sheet/range, the `Value` being searched, and the `Output` variable.
+2. Trace the `Output` downstream — confirm the actual failure is "lookup returned nothing / wrong cell" rather than an exception thrown by the activity.
+3. Inspect the target workbook (or ask the user to) for active filters: open the sheet and check whether the filter/funnel icons are present on the header row, or whether any rows are hidden. The row the search value lives on may be filtered out.
+4. Confirm the search value really is present in a **filtered-out** row (not simply absent or misspelled — that would be a different cause).
+
+## Resolution
+
+- **If active filters are hiding the target rows** — reset or remove the filters before the lookup runs:
+  1. Add a **Filter Table** activity configured to clear the filter, OR a **Clear Sheet/Range/Table** activity (the "clear filters" variant) on the target worksheet, immediately before the `Lookup Range`.
+  2. Re-run. With all rows visible, the lookup sees the full data set and finds the value.
+  - **Who:** RPA developer
+- **If the workbook ships with a saved filter state** — also fix the source workbook (open it, clear the AutoFilter, save) so the filter does not silently reappear on the next run from a fresh copy.
+- **If no filters are present and the value is genuinely absent** — this is not the filter scenario. Re-check the search `Value` for a type/whitespace mismatch against the cell contents (see the invalid-range playbook) before concluding the data is missing.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/lookup-range-excel-not-installed.md

@@ -0,0 +1,36 @@
+---
+confidence: high
+---
+
+# Lookup Range — Excel Is Not Installed / Activity Fails to Initialize
+
+## Context
+
+What this looks like:
+- Activity `Lookup Range` (classic `UiPath.Excel.Activities.ExcelLookUpRange`) faults at initialization, before it reads any cell
+- Error message contains one of: `Excel is not installed`, `Could not load file or assembly 'Microsoft.Office.Interop.Excel'`, `Retrieving the COM class factory for component with CLSID {00024500-0000-0000-C000-000000000046} failed`, `80040154 (REGDB_E_CLASSNOTREG)`, or `Cannot create an instance of Microsoft.Office.Interop.Excel.ApplicationClass`
+- The job faults synchronously the moment the activity (or its surrounding `Excel Application Scope`) tries to launch Excel
+
+What can cause it:
+- The classic `Lookup Range` activity drives the **Microsoft Excel Interop API** — it launches a real Excel.exe via COM. If Microsoft Excel is not installed on the execution machine (a Linux robot, a stripped-down VM, a container image, or a freshly-provisioned unattended host), the COM class factory for `Excel.Application` cannot be created and the activity faults at startup. This is the only cause of the `REGDB_E_CLASSNOTREG` / `Excel is not installed` signature — Interop cannot run without a registered Excel installation.
+
+Notes:
+- Classic `Lookup Range` (`UiPath.Excel.Activities.ExcelLookUpRange`) and any other classic Excel activity inside an `Excel Application Scope` share this dependency. The modern `Lookup Range` (`LookUpRangeX`) inside a `Use Excel File` / `Excel Process Scope` *also* requires Excel installed for most operations.
+- The **Workbook** family of activities (`Read Range` under `Workbook`, not under a scope) reads `.xlsx` via OpenXML and does **not** require Excel — that is the migration target below.
+
+## Investigation
+
+1. Read the faulted activity from the workflow `.xaml` and confirm it is a `Lookup Range` (classic `ExcelLookUpRange` or modern `LookUpRangeX`) inside an `Excel Application Scope` / `Use Excel File` container.
+2. Confirm whether Microsoft Excel is installed on the execution machine. Ask the user (or someone with access to the robot host) to check `Control Panel > Programs and Features` for a Microsoft Office / Microsoft 365 entry, or run `Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\excel.exe` in PowerShell as the robot's Windows user.
+3. Confirm the robot type. Linux robots and many cloud/container unattended hosts have no Excel and cannot run Interop-based activities at all.
+
+## Resolution
+
+- **If Excel can be installed on the host** — install Microsoft Excel (or the full Office / Microsoft 365 desktop suite) on the execution machine under a license the robot's Windows user can activate, then re-run. Interop requires a registered desktop Excel; web/online Excel does not satisfy it.
+- **If Excel cannot be installed** (Linux robot, locked-down VM, container) — re-architect the workflow to avoid Interop:
+  1. Replace the `Lookup Range` + `Excel Application Scope` with the **Workbook** `Read Range` activity (the one under the `Workbook` category, not inside a scope). It reads `.xlsx` through OpenXML with no Excel dependency.
+  2. Output the sheet into a `DataTable` variable.
+  3. Search the `DataTable` with the **Lookup Data Table** activity (returns the matching row index and/or a target-column cell value), which is the OpenXML-friendly equivalent of `Lookup Range`.
+  - **Source:** this is the documented migration path when Excel is unavailable; the classic Interop activity has no in-place workaround on an Excel-less host.
+
+> The modern `Use Excel File` surface still launches Excel for most write/format/macro operations, so migrating from classic `Excel Application Scope` to `Use Excel File` does **not** remove the Excel dependency. Only the `Workbook` (OpenXML) activities are truly Excel-free.

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

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# Lookup Range — Workbook Locked / File In Use
+
+## Context
+
+What this looks like:
+- Activity `Lookup Range` (`UiPath.Excel.Activities.ExcelLookUpRange` / `LookUpRangeX`) — or the surrounding `Excel Application Scope` / `Use Excel File` — faults when it tries to open or read the workbook
+- Error message contains one of: `The process cannot access the file '<path>' because it is being used by another process`, `The file '<name>' is locked for editing by '<user>'`, `IOException`, or a COM `0x800A03EC`/`RPC` error that resolves to a busy/locked workbook
+- The failure is often intermittent — the workflow succeeds when no one has the file open and fails when the file is held
+
+What can cause it:
+- The workbook is **held open by another process**: a user has it open interactively on the host, a previous job or a crashed debug run left an `EXCEL.EXE` instance holding the handle, another concurrent job is reading/writing the same file, or an antivirus/indexer/sync client (OneDrive, backup agent) has a transient lock.
+- Excel cannot acquire the read/write handle it needs, so the open faults before the lookup runs.
+
+Notes:
+- This is distinct from the modern-surface COM dispatcher failure (`0x80010100 RPC_E_SYS_CALL_FAILED`) documented in [invoke-vba-com-interop-failure.md](./invoke-vba-com-interop-failure.md): that one is a *blocked/hung* Excel call, this one is a *file handle* contention. If the message names the **file** being in use, apply this playbook; if it names a COM system-call HRESULT during a macro, apply the COM-interop one.
+- An orphaned `EXCEL.EXE` from a prior run is the most common unattended cause — the file looks closed to a human but the handle is still held by a windowless process.
+
+## Investigation
+
+1. Read the workflow `.xaml`: capture the workbook path the `Excel Application Scope` / `Use Excel File` opens, and confirm the faulted activity is the `Lookup Range` (or the scope wrapping it).
+2. Confirm the error names the **file** as being used by another process (vs. a COM/HRESULT signature — that routes to the COM-interop playbook).
+3. Ask the user (or someone with host access, as the robot's Windows user) to check:
+   - Whether the workbook is open interactively on the robot host.
+   - Whether orphaned `EXCEL.EXE` processes exist (Task Manager, or `Get-Process EXCEL` in PowerShell) with no visible window.
+   - Whether another job/schedule touches the same workbook path in an overlapping window.
+   - Whether a sync client (OneDrive/SharePoint) or backup/AV agent holds the path.
+
+## Resolution
+
+- **If an orphaned `EXCEL.EXE` is holding the file** — make every Excel automation close cleanly and kill strays:
+  1. Wrap the lookup in an `Excel Application Scope` (classic) or `Use Excel File` / `Excel Process Scope` (modern) so the scope's dispose always releases the handle. Ensure no `Try/Catch` swallows the scope exit.
+  2. Add a **Kill Process** activity targeting `EXCEL` at the **start** of the workflow to force-close stray background instances before opening the file. (On the modern surface, the `Excel Process Scope`'s `KillExcelProcessesEachIteration` does this for you.)
+  - **Who:** RPA developer
+- **If a user or another job holds the file** — serialize access: schedule the workflow when the file is not open interactively, dedicate the host to unattended runs, or stagger the conflicting jobs so they do not touch the same workbook concurrently.
+- **If a sync/backup/AV client holds the path** — move the workbook out of the synced/scanned folder, or exclude it from the sync/scan, so the handle is not transiently locked during the run.
+- **If the file is genuinely shared and must stay open** — open it read-only where the activity supports it, or copy the workbook to a private working path at the start of the run and look up against the copy.

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/lookup-range-formula-cells.md

@@ -0,0 +1,53 @@
+---
+confidence: medium
+---
+
+# Lookup Range — Silent Miss Against a Formula Cell
+
+## Context
+
+What this looks like:
+- Activity `Lookup Range` (`UiPath.Excel.Activities.ExcelLookUpRange` / `LookUpRangeX`) completes **without throwing** but returns a null, empty, or unexpected cell address
+- The cell the search value should match is visibly displaying the expected text when the workbook is opened by hand, yet the lookup reports the value is not present
+- The target cell holds an **Excel formula** (the formula bar shows `=...`) — the displayed text is the formula's calculated result, not a static value
+
+What can cause it:
+- `Lookup Range` reads each cell through the Microsoft Excel Interop API. When the target cell is a **formula**, Interop returns whatever Excel has currently cached as the formula's calculated value. If the cache is stale, has not been re-evaluated since a dependency changed, or the formula failed to recompute under the robot's Excel session, the Interop read returns `null`, an empty string, or the previous value — and `Lookup Range` cannot match the search value to a cached miss.
+- Common triggers:
+  - **Volatile functions** (`NOW()`, `TODAY()`, `RAND()`, `INDIRECT(...)`, `OFFSET(...)`) that recompute only on a full recalculation pass.
+  - **Cross-sheet / external-workbook references** (`=Sheet2!A1`, `=[OtherBook.xlsx]Sheet1!A1`) where the source is not loaded or not refreshed in the robot's Excel session.
+  - **Add-in-dependent calculations** — formulas that resolve through a COM add-in (e.g. Bloomberg, Reuters, custom RTD providers) that is not loaded under the unattended robot user.
+  - **Manual calculation mode** on the workbook (`Formulas > Calculation Options > Manual`), so opening the workbook never recomputes formulas the run depends on.
+
+Notes:
+- This is a **silent failure** — there is no error string in the job log from the activity itself. The symptom is a wrong/empty `Output` value, or a downstream fault that traces back to the lookup result. Do not expect a `Lookup Range` error line; inspect what the activity *returned* and what type of cell the search target is.
+- Distinct from the active-filters silent miss ([lookup-range-active-filters.md](./lookup-range-active-filters.md)), which hides rows from the search. Here the row is visible — the formula value Interop reads from it just does not match the search value.
+- Distinct from a type/whitespace mismatch ([lookup-range-invalid-range.md](./lookup-range-invalid-range.md)). The displayed cell text matches; the issue is what the Interop read returns.
+
+## Investigation
+
+1. Read the `Lookup Range` node from the workflow `.xaml`: capture the target sheet/range, the `Value` being searched, and the `Output` variable.
+2. Trace the `Output` downstream — confirm the actual failure is "lookup returned nothing / wrong cell" rather than an exception thrown by the activity.
+3. Inspect the target cell (or ask the user to): open the workbook, click the cell the search value should match, and confirm whether the **formula bar** shows `=...`. If yes, this is a formula cell — proceed with this playbook.
+4. Characterize the formula:
+   - Does it use volatile functions (`NOW`, `TODAY`, `RAND`, `INDIRECT`, `OFFSET`) or other functions that recompute only on a full pass?
+   - Does it reference other sheets or external workbooks (`Sheet2!A1`, `[OtherBook.xlsx]...`)?
+   - Does it depend on a COM add-in (Bloomberg, Reuters, Power Query, custom RTD)?
+   - Is the workbook's calculation mode `Manual` (`Formulas > Calculation Options`)?
+5. Confirm the value the cell *displays* matches the search value visually, but the Interop read is stale or missing (the lookup returns null/empty, not a different-but-similar cell).
+
+## Resolution
+
+- **If the formula's value should be static at the time of the lookup** — convert the formula cells to literal values before the lookup:
+  1. In the source workbook: select the formula cells, `Copy > Paste Special > Values`, then save. The lookup then matches a static text/number cell rather than re-reading a formula result.
+  2. Alternatively, automate this in the workflow: read the range into a DataTable, write the values back as static text, or compute the lookup off the DataTable in step 2 below.
+  - **Who:** RPA developer (or data owner if the workbook is shared)
+- **If the formulas must stay dynamic** — move the lookup off Interop to the Workbook (OpenXML) path:
+  1. Replace the `Lookup Range` + `Excel Application Scope` with the **Workbook** `Read Range` activity (under the `Workbook` category, not inside a scope). It reads the workbook's cached calculated values via OpenXML, without re-evaluating formulas — which makes the lookup deterministic for whatever Excel last saved.
+  2. Output the sheet into a `DataTable`.
+  3. Search the `DataTable` with the **Lookup Data Table** activity. This is the OpenXML-friendly equivalent of `Lookup Range` and matches against static cached values, not against a freshly-computed (and potentially failing) Interop read.
+  - **Source:** the documented migration path for any silent-miss case where Interop cell reads are unreliable.
+- **If the workbook is in `Manual` calculation mode** — force a recalculation at the start of the run (open the workbook with `Visible = True` if needed, or push `F9` / a `Calculate` macro before the lookup), or switch the workbook to `Automatic` calculation and save.
+- **If the formula resolves through an add-in not loaded on the robot host** — either load the add-in for the robot's Windows user (and verify it activates), or freeze the relevant cells to values as above.
+
+After the fix, confirm the lookup returns the expected cell address. If it still returns null with no parse error and no formula on the target cell, check for active filters hiding the row (see [lookup-range-active-filters.md](./lookup-range-active-filters.md)) or a value type/whitespace mismatch ([lookup-range-invalid-range.md](./lookup-range-invalid-range.md)).

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/lookup-range-invalid-range.md

@@ -0,0 +1,42 @@
+---
+confidence: medium
+---
+
+# Lookup Range — Invalid Range Syntax or Value Misconfiguration
+
+## Context
+
+What this looks like:
+- Activity `Lookup Range` (`UiPath.Excel.Activities.ExcelLookUpRange` / `LookUpRangeX`) faults or returns an unpredictable cell address
+- Symptoms vary by misconfiguration:
+  - Range parse error: `The range '<x>' is not valid`, `Reference is not valid`, or a COM `0x800A03EC`
+  - Wrong/garbage `Output` cell address when the search value contains wildcard characters (`*`, `?`, `~`)
+  - Type-mismatch miss: the value exists as displayed but the lookup does not match it because the searched type differs from the stored cell type
+
+What can cause it (any of):
+- **Malformed `Range` field** — an invalid A1 reference, or the common mistake of typing an empty string `""` into the `Range` property expecting "whole sheet". For `Lookup Range`, the whole-sheet search is expressed by leaving the `Range` field **completely empty** (no value at all), not by an empty-string literal `""`.
+- **Unescaped wildcards in the search `Value`** — a search string containing `*`, `?`, or `~` is interpreted as an Excel wildcard pattern, so the lookup matches the wrong cell or returns an unexpected address instead of a literal-text match.
+- **Type mismatch on the search `Value`** — a number stored as text vs. a numeric cell, a date passed as a string, or a trailing/leading space, so the equality check fails even though the value "looks" present.
+
+Notes:
+- The empty-string-vs-empty-field distinction is the single most common version of this. `Range = ""` is a *value* (an invalid range) and can crash or mis-resolve; `Range` left blank is the documented way to search the entire used range.
+
+## Investigation
+
+1. Read the `Lookup Range` node from the workflow `.xaml`: capture the literal `Range` value, the `Value` expression being searched, and the `Output` variable.
+2. Inspect the `Range` field:
+   - If it holds an empty-string literal `""`, that is the misconfiguration — it should be genuinely empty for a whole-sheet search.
+   - If it holds an A1 reference, validate the syntax (valid column letters, valid row numbers, valid `Sheet!A1:B2` form if sheet-qualified).
+3. Inspect the search `Value`:
+   - Check for wildcard characters (`*`, `?`, `~`) in the literal or the bound variable.
+   - Check the data type against the target cells: is the workflow searching a `String` against numeric/date cells, or vice versa? Look for stored-as-text numbers and stray whitespace.
+
+## Resolution
+
+- **If `Range` is an empty-string `""`** — clear the field entirely (leave it blank) to search the whole used range. Do not pass `""`.
+  - **Source:** documented behavior — blank `Range` = whole sheet; `""` is an invalid range value.
+- **If `Range` is a malformed A1 reference** — correct it to a valid reference (e.g. `A1:D500`, or `Sheet1!A:A` for a full column). Sheet-qualify it if the active sheet is ambiguous.
+- **If the search `Value` contains wildcards that should be literal** — escape them so they are matched literally (prefix `~` before a literal `*` or `?`, i.e. `~*`, `~?`), or pre-clean the value, so the lookup does a literal-text match instead of a pattern match.
+- **If the `Value` type does not match the cell type** — align the types: convert the search value to match how the data is stored (e.g. `.ToString()` for text-stored numbers, trim whitespace with `.Trim()`, or parse to the numeric/date type the cells use). A value that "looks" present but does not match is almost always a text-vs-number or whitespace mismatch.
+
+After the fix, confirm the lookup returns the expected cell address. If it still returns null with no parse error and no type issue, check for active filters hiding the row (see [lookup-range-active-filters.md](./lookup-range-active-filters.md)).

package/skills/uipath-troubleshoot/references/activity-packages/excel-activities/playbooks/lookup-range-null-reference.md

@@ -0,0 +1,37 @@
+---
+confidence: medium
+---
+
+# Lookup Range — Object Reference Not Set (Sheet or Range Missing / No Scope)
+
+## Context
+
+What this looks like:
+- Activity `Lookup Range` (`UiPath.Excel.Activities.ExcelLookUpRange` / `LookUpRangeX`) faults with `Object reference not set to an instance of an object` (`System.NullReferenceException`)
+- The fault is synchronous, the moment the activity tries to resolve its target sheet or range
+- No file-in-use message (that routes to [lookup-range-file-locked.md](./lookup-range-file-locked.md)) and no `Excel is not installed` message (that routes to [lookup-range-excel-not-installed.md](./lookup-range-excel-not-installed.md))
+
+What can cause it (any of):
+- **Target sheet does not exist** — the `SheetName` configured on the activity (or implied by the range) names a sheet that is absent from the workbook: a typo, a rename, a case/whitespace difference, or the wrong workbook is open. The activity dereferences a null worksheet handle.
+- **Target range does not resolve** — the named range or table the activity points at is not defined in the workbook, so the range object is null.
+- **No surrounding scope / workbook not opened** — the classic `Lookup Range` was dropped outside an `Excel Application Scope`, or the modern `LookUpRangeX` outside a `Use Excel File` / `Excel Process Scope`, so there is no workbook context object and the activity dereferences null. (Also occurs when the scope failed to open earlier but execution continued.)
+
+Notes:
+- `NullReferenceException` is a generic .NET fault; the *Excel-specific* root cause is almost always one of the three above for this activity. The generic runtime-exception playbook in `runtime-exceptions/playbooks/null-reference-exception.md` covers null faults in user workflow code — this playbook is for the null fault originating *inside* the `Lookup Range` activity's sheet/range/scope resolution.
+- A sheet-name mismatch here is the direct analogue of the GSuite "sheet does not exist" and the asset-name-mismatch patterns: exact-match lookup, no fuzzy fallback.
+
+## Investigation
+
+1. Read the `Lookup Range` node from the workflow `.xaml`: capture the configured `SheetName`, the range/table reference, and whether the activity sits inside an `Excel Application Scope` / `Use Excel File` container.
+2. Confirm the surrounding scope exists and opened successfully (check the job log for a successful "workbook opened" line before the fault; if the scope itself faulted, fix that first).
+3. Open the target workbook (or ask the user to) and list the actual sheet/tab names. Compare against the activity's `SheetName` character-for-character — watch for trailing spaces, case differences, and similar-looking names.
+4. If the activity references a named range or table, confirm that name is actually defined in the workbook (`Formulas > Name Manager`).
+
+## Resolution
+
+- **If the sheet name does not match** — fix the `SheetName` on the activity to match the workbook's tab name exactly (case and spacing included), or rename/add the sheet in the workbook so the configured name resolves. Save, rebuild, republish.
+- **If the named range/table is undefined** — define it in the workbook (`Name Manager` / format-as-table), or change the activity to address an explicit A1 range instead of the missing name.
+- **If the activity is not inside a scope** — wrap it: classic `Lookup Range` inside an `Excel Application Scope`, modern `LookUpRangeX` inside a `Use Excel File` / `Excel Process Scope` bound to the workbook. Without the scope there is no workbook context and the activity always null-faults.
+- **If the scope opened the wrong workbook** — correct the `WorkbookPath` so the sheet the activity expects is actually present in the opened file.
+
+After the fix, confirm the lookup resolves a real cell address rather than returning null — a silent null result with active filters present is a *different* scenario (see [lookup-range-active-filters.md](./lookup-range-active-filters.md)).

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

@@ -0,0 +1,9 @@
+# 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

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

@@ -0,0 +1,17 @@
+# Excel Activities Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Excel Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Invoke VBA — Trust Access to VBA Project Denied | High | Excel "Trust access to the VBA project object model" setting disabled; activity cannot inject the macro module | [invoke-vba-trust-access.md](./playbooks/invoke-vba-trust-access.md) |
+| Invoke VBA — Cannot Run Macro / Code File Unreadable | Medium | External `.txt`/`.vba` code file missing, malformed, wrongly encoded, or not wrapped in a `Sub`/`Function` block | [invoke-vba-code-file-path.md](./playbooks/invoke-vba-code-file-path.md) |
+| Invoke VBA — Entry Method Name Mismatch | High | `EntryMethodName` does not resolve to a `Sub`/`Function` declared in the code file (typo, parentheses appended, nested macro) | [invoke-vba-entry-method-name.md](./playbooks/invoke-vba-entry-method-name.md) |
+| Invoke VBA — Parameter Type or Shape Mismatch | Medium | `EntryMethodParameters` is not a properly-built `IEnumerable<Object>`, arity is wrong, or values were typed inline in the property window | [invoke-vba-parameter-formatting.md](./playbooks/invoke-vba-parameter-formatting.md) |
+| Invoke VBA — COM Interop Failure (0x80010100) | Medium | Excel busy, blocked by a hidden modal dialog, Excel.exe hung, or multiple/wrong-bitness Office installs | [invoke-vba-com-interop-failure.md](./playbooks/invoke-vba-com-interop-failure.md) |
+| Lookup Range — Excel Not Installed | High | Classic `Lookup Range` Interop init fails on a host without Excel (`REGDB_E_CLASSNOTREG`); migrate to Workbook Read Range + Lookup Data Table | [lookup-range-excel-not-installed.md](./playbooks/lookup-range-excel-not-installed.md) |
+| Lookup Range — Value Not Found (Active Filters) | Medium | Active AutoFilters hide the target row; activity returns null/empty silently and a downstream fault is the first symptom | [lookup-range-active-filters.md](./playbooks/lookup-range-active-filters.md) |
+| Lookup Range — Workbook Locked / File In Use | Medium | Workbook held by another process, orphaned `EXCEL.EXE`, concurrent job, or sync/AV client; `being used by another process` | [lookup-range-file-locked.md](./playbooks/lookup-range-file-locked.md) |
+| Lookup Range — Object Reference Not Set | Medium | `NullReferenceException` from a missing sheet/range name or the activity running outside an Excel scope | [lookup-range-null-reference.md](./playbooks/lookup-range-null-reference.md) |
+| Lookup Range — Invalid Range or Value | Medium | `Range` set to `""` instead of blank, malformed A1 reference, unescaped wildcards, or a text-vs-number type mismatch in the search value | [lookup-range-invalid-range.md](./playbooks/lookup-range-invalid-range.md) |
+| Lookup Range — Silent Miss Against a Formula Cell | Medium | Target value is the *computed* result of an Excel formula; Interop reads a stale/null cached value or fails to re-evaluate, so the lookup returns null even though the displayed text matches | [lookup-range-formula-cells.md](./playbooks/lookup-range-formula-cells.md) |

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

@@ -0,0 +1,28 @@
+# Google Workspace Activities Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity's namespace and class match the reported failure (e.g., `UiPath.GSuite.Activities.GetNewestEmailConnections`). Modern `*Connections` activities and legacy classic activities sometimes share display names but run different code paths — treat them as different.
+- **Connection / Google account** — the Integration Service connection in evidence authenticates against the same Google account the user is asking about. Different connections = different mailboxes, different Drive scopes, different shared drives = unrelated data.
+- **Target resource** — the resource identifier in evidence matches the one the user reports: Gmail mailbox label/folder, Drive file/folder ID or URL, spreadsheet ID, document ID, calendar ID. Don't substitute a similarly-named resource.
+- **Workflow file** — if the project contains multiple workflows, the error originates from the workflow the user is asking about, not a different `.xaml` / `.cs` that happens to use the same activity.
+- **Timestamp** — the failure occurred during the time window the user reported. Load-bearing for filter-based Gmail activities (only messages received at or before the run time are eligible) and for quota investigations (storage state may have changed since).
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## 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.
+
+## Testing Prerequisites
+
+When testing hypotheses for Google Workspace Activities issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — capture both the class name and the display name from the workflow source or stack trace. 
+2. **Target Google service** — identify whether the call lands on Gmail, Drive, Sheets, Docs, Calendar, Tasks, Forms, or Apps Script. The same Google API status code (404 / 403 / 429) surfaces with different wording and different remediation per service.
+3. **Connection target** — capture the Integration Service connection name and the underlying Google account email it authenticates as. For shared-drive operations, also capture which shared drive is in scope.
+4. **Activity input properties** — capture every input property the activity uses to address its target, from the workflow source (not from a summary): filter collections, `ConflictResolution`, target identifiers (ID / URL / path / browse selection), `SheetName`, source local paths. The playbook the agent is following will name the subset that matters.
+5. **Job run timestamp** — exact time the activity executed. Required for filter-based Gmail investigations (mailbox state at run time) and for upload quota investigations (storage state at time of failure).
+6. **Package version** — `UiPath.GSuite.Activities` version. Behavior, exception messages, and supported `ConflictResolution` values have shifted across versions; version-specific bugs are documented in playbooks as they're discovered.

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

@@ -0,0 +1,54 @@
+# Google Workspace Activities
+
+Activities from the `UiPath.GSuite.Activities` package for automating Google Workspace services: Gmail, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Tasks, Google Forms, and Apps Script. Modern activities call Google REST APIs through OAuth-authenticated connections managed by Integration Service; legacy XAML activities use a `GSuiteApplicationScope` container (Windows only).
+
+## How Connections Work
+
+Modern activities are suffixed `*Connections` (e.g., `GetNewestEmailConnections`). When the activity executes, it:
+
+1. Resolves the configured Integration Service connection to obtain an OAuth access token
+2. Issues a Google REST API request (Gmail, Drive, Sheets, Calendar, Docs, Tasks, Forms, or Apps Script)
+3. Maps the Google API response back into the activity output, or throws on error
+
+Failures can originate at any of those layers — connection resolution (Integration Service), token validation (Google OAuth), the API call itself (Google service), or post-processing inside the activity. Knowing which layer produced the error narrows the investigation.
+
+## Key Activity Types
+
+### Gmail
+
+- **Get Newest Email** (`GetNewestEmailConnections`) — retrieves the single most recent message matching a configured filter.
+- **Send / Reply / Forward Email** (`SendEmailConnections`, `ReplyToEmailConnections`, `ForwardEmailConnections`) — send, reply, or forward a Gmail message. Uploads attachments via Gmail multipart upload, so they share Drive-class quota failures.
+
+### Drive
+
+- **Item write operations** (`CreateFolderConnections`, `CopyFileConnections`, `MoveFileConnections`, `RenameFileFolderConnections`, `UploadFilesConnections`, `CreateSpreadsheetConnections`, `CreateDocumentConnections`) — create, copy, move, rename, or upload Drive items; behavior on duplicate name in the destination is governed by the `ConflictResolution` enum (`Replace`, `Fail`, `Rename`, `AddSeparate`, `UseExisting`).
+- **Item resolution by ID, URL, or path** (most Drive activities, e.g., `GetFileFolderConnections`, `GetFileFolderInfoConnections`, `DownloadFileConnections`, `DeleteFileOrFolderConnections`, `ShareFileFolderConnections`, plus the write operations above) — resolve a target file or folder against the Drive API; fails with HTTP 404 when the identifier no longer resolves.
+- **Upload Files** (`UploadFilesConnections`, legacy `UploadFile`) — upload local files into Drive via multipart upload; subject to user storage quota and shared-drive file-count limit.
+
+### Sheets
+
+- **Add Sheet** (`AddSheetConnections`) — add a new sheet (tab) to an existing spreadsheet; behavior on duplicate sheet name is governed by `ConflictResolution` (`Fail`, `Replace`, `Rename`).
+- **Cell-writing / grid-expanding activities** (`WriteRangeConnections`, `WriteCellConnections`, `WriteRowConnections`, `WriteColumnConnections`, `AutoFillRangeConnections`, `CopyPasteRangeConnections`, `AddSheetConnections`, plus legacy `WriteCell`, `WriteRange`, `AppendRow`, `AddNewSheet`, `AddDeleteColumns`, `AddDeleteRows`, `AutoFillRange`, `CopyPasteRange`, `CopySheet`, `BatchUpdateValuesScope`) — write cells or expand the bounded grid; auto-expansion makes them subject to the spreadsheet-wide 10,000,000-cell cap. `CopySheet` is legacy-only and the most aggressive trigger.
+- **Range-addressed activities** (`ReadCellConnections`, `ReadRangeConnections`, `ReadRowConnections`, `ReadColumnConnections`, `WriteCellConnections`, `WriteRangeConnections`, `WriteRowConnections`, `WriteColumnConnections`, `AutoFillRangeConnections`, `CopyPasteRangeConnections`, `DeleteRangeConnections`, `ForEachRowConnections`, `SetRangeColorConnections`, `GetCellColorConnections`, plus legacy `ReadCell`, `ReadRange`, `ReadRow`, `ReadColumn`, `WriteCell`, `WriteRange`, `AutoFillRange`, `CopyPasteRange`, `ClearRange`, `DeleteRange`, `ForEachSheetRow`, `GetCellColor`) — accept a range or cell address in A1 notation; the supplied range is forwarded to the Google Sheets API and validated server-side.
+
+## Common Failure Patterns
+
+### Gmail
+
+- **Filter returns no matching email** — Gmail mailbox contains zero messages matching the configured filter at the moment the activity runs. `Get Newest Email` throws `GmailException: No email matching the search criteria has been found` synchronously, with no retry or wait.
+
+### Drive
+
+- **Item name conflict** — Drive write activity throws `GSuiteException: Multiple items with the name <name> found in the specified folder.` when the target folder already contains an item with that name and `ConflictResolution` cannot resolve the duplicate. Affects Create Folder, Copy File, Move File, Rename, Upload, Create Spreadsheet, and Create Document.
+- **404 — file or folder not found** — A Drive activity fails to resolve the configured ID, URL, or path because the resource was deleted, trashed, or is not accessible to the connection. Surfaces as one of: `File not found: <id>. [404]` (raw `Google.GoogleApiException`), `The service drive has thrown an exception. HttpStatusCode is NotFound. ...` (wrapped form), or `The resource was not found.` (translated form).
+- **Upload storage quota or shared drive file limit exceeded** — Drive or Gmail attachment upload throws `GSuiteException: Upload failed after <N> bytes. ...` carrying a Google 403. Two underlying conditions: `storageQuotaExceeded` (user's Drive storage full) or `The file limit for this shared drive has been exceeded.` (shared drive at the 500K item cap). Affects `UploadFilesConnections`, legacy `UploadFile`, and Gmail send/reply/forward when the message has attachments.
+
+### Sheets
+
+- **Sheet name conflict** — `Add Sheet` throws `GSuiteException: A sheet with the same name already exists.` when the spreadsheet already contains a sheet with the configured `SheetName` (case-insensitive) and `ConflictResolution = Fail`. Restricted to `AddSheetConnections`.
+- **10,000,000-cell limit exceeded** — Sheets write or grid-expand activity throws `GSuiteException` carrying a Google 400 BadRequest: `This action would increase the number of cells in the workbook above the limit of 10000000 cells.` The cap is the sum of the bounded grid (rows × columns) across every sheet in the spreadsheet, including empty cells. Hard Google quota; cannot be raised. Affects all cell-writing / grid-expanding Sheets activities.
+- **Invalid range — unable to parse** — Range-addressed Sheets activity throws `GSuiteException` carrying a Google 400 BadRequest: `Invalid data[0]: Unable to parse range: <SheetName>!<CellRef>`. Common causes: 1-indexing mistake (`A0`), empty/null range variable, sheet name with spaces or special characters not single-quoted in A1 notation, stale sheet reference after a rename, or off-by-one in a dynamically-built address. Affects all range-addressed Sheets activities.
+
+## Package
+
+NuGet: `UiPath.GSuite.Activities`

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/add-sheet-name-conflict.md

@@ -0,0 +1,29 @@
+---
+confidence: high
+---
+
+# GSuite Add Sheet — A sheet with the same name already exists
+
+## Context
+
+What this looks like:
+- Activity `Add Sheet` (`UiPath.GSuite.Activities.AddSheetConnections`) throws `GSuiteException`
+- Error message: `A sheet with the same name already exists.`
+- Job faults synchronously the moment the activity runs
+
+What can cause it:
+- The target spreadsheet already contains a sheet (tab) whose title equals the configured `SheetName` (case-insensitive comparison), and `ConflictResolution` is set to `Fail`. This is the only cause — Google Sheets does not permit two sheets with the same name within one spreadsheet, and the `Fail` branch refuses to proceed when a duplicate is detected.
+
+Notes:
+- `AddSheetConnections` is the only GSuite activity that produces this exception. Other Sheets activities (`AddSheetConnections` aside) do not exercise this code path.
+- The default value of `ConflictResolution` on `AddSheetConnections` is `Fail`, so this is the out-of-the-box behavior when the property is left unset.
+
+## Resolution
+
+A spreadsheet cannot contain two sheets with the same name. The error is unambiguous; no further investigation is needed. Stop the investigation and ask the user to do one of the following:
+
+1. **Change the `SheetName`** on the activity so it is unique within the target spreadsheet (remember: matching is case-insensitive — `"Data"` and `"data"` collide).
+2. **Ensure the target spreadsheet contains no sheet with that name** (rename or delete the existing sheet first).
+3. **Change `ConflictResolution`** on the activity to a value that handles the duplicate:
+   - `Replace` — delete the existing sheet with that name and add a new sheet at the same position
+   - `Rename` — automatically rename the new sheet to a unique name (appends `1`, `2`, … until no collision remains)