@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/database-activities/playbooks/execute-non-query-failures.md

@@ -0,0 +1,97 @@
+---
+confidence: medium
+---
+
+# Execute Non Query Failures
+
+## Context
+
+A `UiPath.Database.Activities` `Execute Non Query` (`ExecuteNonQuery`) activity runs a data-modifying statement — `INSERT` / `UPDATE` / `DELETE` / DDL (`CREATE`/`ALTER`) — or a stored procedure, and returns the affected-row count in its `AffectedRecords` output (`Int32`). Like `Execute Query` it takes a connection via `ExistingDbConnection` (from `Connect to Database` / `Start Transaction`) or an inline `ConnectionString` + `ProviderName`, plus `Sql`, `CommandType` (`Text` / `StoredProcedure`), `Parameters`, and `TimeoutMS`. Failures cluster around four surfaces: stored-procedure output-parameter sizing, statement/parameter construction, an empty command, and missing/mismatched database drivers.
+
+Rule out the wrong-activity case first: **`Execute Non Query` is for modifications; `Execute Query` is for `SELECT`** (→ `DataTable`). Using `Execute Non Query` to pull data, or `Execute Query` to modify, is a category error — see [execute-query-failures.md](./execute-query-failures.md) branch 7.
+
+What this looks like — Execute Non Query faults surface as one of these signatures:
+
+- `The Size property has an invalid size of 0` (from the ODBC/ADO.NET layer) — branch 1.
+- `Execute Non Query: A database error occurred` wrapping a provider syntax error (`Incorrect syntax near ...`, `ORA-…`), or a type/cast error mapping a value into a column — branch 2.
+- `CommandText property has not been initialized` (ADO.NET) — branch 3.
+- `Failed to load library (ErrorCode: 126)` / `System.DllNotFoundException` / a provider that "is not registered" or fails to load — branch 4.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Stored-procedure output parameter with `Size = 0` (ODBC)** — a stored procedure invoked with `CommandType: StoredProcedure` that has an `Output` / `InputOutput` parameter, run through an ODBC driver (e.g. SQL Server over ODBC). The driver cannot infer the memory footprint of the returned value when the parameter's `Size` is left at `0`, so it throws `The Size property has an invalid size of 0`.
+2. **Unsafe SQL construction / parameter mapping / wrong type** — the `Sql` is built by concatenating values (`"INSERT INTO Users VALUES ('" + strName + "')"`), which breaks on quotes/symbols and is a SQL-injection vector; or a parameter's `Type`/`Direction` is wrong; or the workflow tries to push a whole `DataTable` into a single column. The provider rejects the statement with a syntax or type/cast error wrapped as `A database error occurred`.
+3. **Empty `Sql` (`CommandText property has not been initialized`)** — the `Sql` property is blank, an expression that resolved to `""`, or a variable that was never set / went out of scope. ADO.NET refuses to execute a command with no `CommandText`.
+4. **Driver / client library not loadable (`ErrorCode: 126`)** — the Robot host lacks the database driver or client the connection string needs (Oracle Client, an OLE DB provider, a specific ODBC system driver), or the installed driver's bitness does not match the process. The native load fails with `Failed to load library (ErrorCode: 126)` / `DllNotFoundException`.
+
+What to look for:
+
+- **The exception text** — first signal, maps directly to a branch per the list above. Read the **inner** provider/driver exception, not just the UiPath `A database error occurred` wrapper.
+- **`CommandType` and the `Parameters` collection** — whether the statement is a `StoredProcedure` with `Output`/`InputOutput` parameters, and each parameter's `Name`, `Direction`, `Type`, `Value`, and **`Size`**. Branch 1 is specifically an output parameter with `Size = 0` over ODBC.
+- **How `Sql` is constructed** — literal vs concatenation vs an expression that can resolve empty (branches 2 and 3).
+- **`ProviderName` + driver inventory on the Robot host** — the provider invariant name and whether the matching driver/client is installed at the right bitness (branch 4).
+- **Connection provenance** — inline vs `ExistingDbConnection`, and whether that connection is live (a closed/expired/null connection routes to [execute-query-failures.md](./execute-query-failures.md) branch 1).
+- **`UiPath.Database.Activities` version** — branch 1's ODBC sizing bug was patched in older releases (historically 1.4.0+); branch 4 driver behaviour is also version/host-sensitive.
+
+## 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`: the exception class and full message, including the inner exception. From workflow source (`.xaml`): the `Execute Non Query` node — connection source, `Sql`, `CommandType`, the `Parameters` collection (per-parameter `Direction`/`Type`/`Size`), and `ProviderName`. From job logs (`uip or jobs logs <key> --output json`): the resolved values at the failing step.
+
+2. **Branch the diagnostic on the signature.**
+   - `The Size property has an invalid size of 0` → branch 1; go to step 3.
+   - `A database error occurred` wrapping a syntax / type-cast error → branch 2; go to step 4.
+   - `CommandText property has not been initialized` → branch 3; go to step 5.
+   - `Failed to load library (ErrorCode: 126)` / `DllNotFoundException` / provider load failure → branch 4; go to step 6.
+
+3. **Confirm branch 1 (output-parameter size).** Confirm `CommandType: StoredProcedure`, an `Output`/`InputOutput` parameter, and an ODBC `ProviderName`. Check that parameter's `Size` — `0` (unset) confirms the branch. Note the `UiPath.Database.Activities` version.
+
+4. **Confirm branch 2 (SQL construction / parameters).** Read the inner provider message (it names the offending token or type). In source, check whether `Sql` is concatenated, whether any parameter's `Type`/`Direction` mismatches the column, and whether a `DataTable` is being mapped into a scalar column.
+
+5. **Confirm branch 3 (empty Sql).** Inspect the `Sql` property. If literal, confirm it is non-empty. If an expression, log the resolved value immediately before the activity (`Log Message Level=Info Message=$"SQL: '{sqlText}'"`) and rerun — an empty/`Nothing` result confirms the branch.
+
+6. **Confirm branch 4 (driver load).** Read `ProviderName` and the connection string's driver/client requirement. Check the Robot host for the matching driver/client and its bitness (a **Windows** project is a 64-bit process and needs the 64-bit driver). `ErrorCode: 126` ("module not found") with the required client absent or wrong-bitness confirms the branch. This is the same driver/bitness family as [connect-to-database-failures.md](./connect-to-database-failures.md) branch 2.
+
+The root cause must name **which of the four surfaces** the failure maps to, with the specific evidence: the inner exception, the `CommandType`/`Parameters`/`Sql`/`ProviderName` values, and (branches 1/4) the package version and host driver inventory. A generic "Execute Non Query failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Output parameter `Size = 0` (ODBC stored proc):**
+  - In the `Parameters` collection, set the output parameter's `Size` to the column's maximum (e.g. `50` for `VARCHAR(50)`, `4` for an `INT`). The driver needs an explicit buffer size for the returned value.
+  - Alternatively / additionally, update `UiPath.Database.Activities` to a version where the ODBC sizing bug was patched (historically `1.4.0`+); current packages include the fix.
+
+- **Branch 2 — SQL construction / parameter mapping:**
+  - Do **not** concatenate values into the `Sql`. Use named parameters: `INSERT INTO Users (Name, Age) VALUES (@ParamName, @ParamAge)`, and map each in the `Parameters` collection (`Name: @ParamName`, `Direction: In`, `Type: String`, `Value: strName`). The provider handles quoting/typing and the injection risk goes away.
+  - Match each parameter's `Type`/`Direction` to its column. Do not map a `DataTable` into a scalar column.
+  - To write an entire `DataTable` to a table in one shot, use **Bulk Insert** or **Bulk Update Database** (both in `UiPath.Database.Activities`), not a per-row `Execute Non Query`.
+
+- **Branch 3 — Empty `Sql`:**
+  - Ensure the `Sql` property contains a valid non-empty statement. For expression-built SQL, guard against empty (`If` skip when blank) and log the resolved value before the activity. Fix the upstream assignment / scope so the variable is populated when the activity runs.
+
+- **Branch 4 — Driver / client library not loadable:**
+  - Install the database driver/client the connection string requires (Oracle Client, the OLE DB provider, the ODBC system driver) on every Robot host, at the **bitness matching the process** (64-bit for a **Windows** project — not Office's or the dev machine's bitness).
+  - Verify connectivity with **Configure Connection** on the activity from the host. For the OLE-DB-provider-not-registered variant, see [connect-to-database-failures.md](./connect-to-database-failures.md) branch 2.
+
+## Anti-patterns (what NOT to do)
+
+- **"Concatenate the values into the INSERT/UPDATE string."** (`"INSERT INTO Users VALUES ('" + strName + "')"`) — breaks on quotes/symbols, throws branch-2 syntax errors, and is a SQL-injection hole. Always use named parameters via the `Parameters` collection.
+- **"Loop Execute Non Query once per DataTable row."** For bulk writes this is slow and error-prone; use **Bulk Insert** / **Bulk Update Database**. A per-row loop also tends to surface branch-2 type mismatches one row at a time.
+- **"Wrap Execute Non Query in a Try Catch and continue on error."** A bare catch that swallows the exception leaves the database half-modified and the workflow proceeding as if the write succeeded — worse than failing loudly. Use Try-Catch only with a real recovery path (roll back the transaction, mark the queue item Failed, re-throw a domain exception), and prefer `Start Transaction` so a mid-batch failure rolls back cleanly.
+- **"Use Execute Non Query to read data."** It returns an affected-row count, not rows. For `SELECT`, use `Execute Query` (→ `DataTable`).
+
+## Prevention (cross-branch)
+
+- Parameterize every statement with named parameters; never concatenate. This prevents branch 2 and closes the injection risk.
+- For stored procedures with output parameters over ODBC, always set each output parameter's `Size` explicitly (branch 1).
+- Choose the activity by intent: `Execute Non Query` for modifications, `Execute Query` for `SELECT`, **Bulk Insert/Update** for whole-`DataTable` writes.
+- Provision Robot hosts with the required DB driver/client at the correct bitness, and verify with Configure Connection during host setup (branch 4).
+- Wrap multi-statement modifications in `Start Transaction` so a failure rolls back rather than leaving partial writes.
+
+## Related
+
+- [execute-query-failures.md](./execute-query-failures.md) — the read-side activity; shares the connection (null/expired), SQL-syntax, and timeout surfaces, and owns the wrong-activity branch (Execute Query vs Execute Non Query).
+- [connect-to-database-failures.md](./connect-to-database-failures.md) — branch 4 here (driver/bitness) is the same family as that playbook's provider-not-registered branch.
+- [`../overview.md`](../overview.md) — package connection model and the Bulk Insert / Bulk Update Database activities.

package/skills/uipath-troubleshoot/references/activity-packages/database-activities/playbooks/execute-query-failures.md

@@ -0,0 +1,134 @@
+---
+confidence: medium
+---
+
+# Execute Query Failures
+
+## Context
+
+A `UiPath.Database.Activities` `Execute Query` activity runs a SQL `SELECT` against a database and returns the result set as a `DataTable`. It needs a live connection, supplied one of two ways: an `ExistingDbConnection` produced by a preceding `Connect to Database` activity (or a `Start Transaction` block), or an inline `ConnectionString` + `ProviderName` set on the activity itself. Failures originate at one of seven surfaces: connection handle (null / expired / out of scope), driver provider (post-migration keyword/driver mismatch), SQL text (syntax error or unsafe concatenation), property misplacement (query pasted into the connection-string field), command timeout, CLR-level crash (oversized result set or incompatible native provider), or wrong activity for the statement type.
+
+What this looks like — Execute Query faults surface as one of these signatures:
+
+- `Object reference not set to an instance of an object` (`System.NullReferenceException`) raised at the activity — branch 1.
+- `Keyword not supported: '<keyword>'` / `System.ArgumentException` from the connection-string parser, or a SqlClient native crash, typically right after a Windows-Legacy → Windows project migration — branch 2.
+- `Execute Query: A database error occurred` wrapping a provider exception with `Incorrect syntax near ...` (SQL Server), `ORA-00900: invalid SQL statement` (Oracle), or `You have an error in your SQL syntax` (MySQL) — branch 3.
+- A provider error naming a database that does not exist, or a connection-string parse failure where the offending value is clearly SQL text (`SELECT ...`) — branch 4.
+- `Execute Query: Timeout expired` / `... Timeout period elapsed prior to completion of the operation` — branch 5.
+- The job terminates with exit code `0xE0434352` and no clean activity-level exception in the workflow log — branch 6.
+- An `Execute Non Query` result assigned to a `DataTable` (design-time/cast error), or `Execute Query` used for an `INSERT`/`UPDATE`/`DELETE` (runs but returns an empty/unexpected `DataTable`) — branch 7.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Null / expired / out-of-scope connection** — the `DatabaseConnection` passed to `Execute Query` is `Nothing`. Causes: the `Connect to Database` / `Start Transaction` activity did not run before `Execute Query` (wrong ordering, or it sits on a branch that was skipped); the connect activity's output variable does not match the `ExistingDbConnection` input on the query (different variable, or never wired); the connection variable is scoped to an inner `Sequence` and is out of scope where `Execute Query` runs; or the connection was opened, used, and disposed (e.g., the `Connect` was inside a `Using`/scope that already closed) so the handle is expired.
+2. **Driver provider mismatch after migration** — surfaces after upgrading the project from **Windows - Legacy** (.NET Framework) to **Windows** (.NET 6+). The legacy `System.Data.SqlClient` provider is not the modern default; connection-string keywords valid under one provider are rejected by the other (`Keyword not supported`). MySQL/other engines need an explicitly installed managed/ODBC driver that the legacy runtime bundled implicitly.
+3. **SQL syntax error / unsafe concatenation** — the `Sql` text is malformed, or the workflow builds it by concatenating variables into the string (`"... WHERE id = " + myVar`). Concatenation breaks on quotes/types, fails to parse, and is a SQL-injection vector. The provider rejects the statement with its own syntax error, wrapped by UiPath as `A database error occurred`.
+4. **Query text in the connection-string property** — the SQL statement was pasted into the `ConnectionString` property (or the `Connect` activity's connection field) instead of the `Sql` / query property; or the connection string has unbalanced quotes. The connection-string parser then chokes on the SQL text, often surfacing as a truncated/garbled "database does not exist" because it reads the first token as a database name.
+5. **Command timeout exceeded** — the query ran longer than the activity's `TimeoutMS` (milliseconds; default `30000` = 30 s). Causes: an un-indexed scan, a lock/blocking on the DB side, or a genuinely large/expensive query. The provider aborts and UiPath surfaces `Timeout expired`.
+6. **CLR-level crash (`0xE0434352`)** — a low-level managed-runtime fault that bypasses the normal activity exception path. For `Execute Query` the DB-specific triggers are: a result set large enough to exhaust the Robot process memory (materializing millions of rows into a `DataTable`), an incompatible native provider path (notably Oracle `REF CURSOR` handling), or a stale/incompatible `UiPath.Database.Activities` build. `0xE0434352` is the generic .NET unhandled-exception SEH code — it is not DB-specific on its own; the DB context narrows it.
+7. **Wrong activity for the statement type** — `Execute Query` is for `SELECT` (returns a `DataTable`); `Execute Non Query` is for `INSERT`/`UPDATE`/`DELETE`/DDL (returns the affected-row count in its `AffectedRecords` output, an `Int32`). Using `Execute Query` for a modification returns an empty/meaningless `DataTable` and may error on statements that produce no result set; assigning an `Execute Non Query` `AffectedRecords` result to a `DataTable` fails to compile / casts wrong.
+
+What to look for:
+
+- **The exception class and message** — first signal, maps directly to a branch per the signature list above. A bare `A database error occurred` always wraps an inner provider exception — read the inner message (it carries the real syntax error or provider code).
+- **How the connection is supplied** — from workflow source: whether `Execute Query` reads an `ExistingDbConnection` variable (and which `Connect`/`Start Transaction` activity produces it) or carries an inline `ConnectionString` + `ProviderName`. Trace the variable's producer and scope. This separates branch 1 (broken wiring/scope) from branches 2/4 (inline config problems).
+- **Project compatibility** — whether the project is **Windows** or **Windows - Legacy**, and whether the failure started immediately after a migration. Load-bearing for branch 2.
+- **The `Sql` value** — literal vs expression; whether it is built by concatenation (branch 3) and whether it actually landed in the `Sql` property rather than the connection field (branch 4).
+- **`TimeoutMS` property** (milliseconds) and the DB-side duration of the query — branch 5.
+- **Result-set size and provider** — expected row count, and whether the engine is Oracle with `REF CURSOR` output — branch 6.
+- **`UiPath.Database.Activities` package version** — branches 2 and 6 are version-sensitive.
+
+## 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`: the exception class and full message, *including the inner exception* (the provider's real error). From workflow source (`.xaml`): the `Execute Query` node — whether it uses `ExistingDbConnection` or inline `ConnectionString`/`ProviderName`, the literal `Sql` text or bound expression, and `TimeoutMS`. From job logs (`uip or jobs logs <key> --output json`): Trace lines showing the resolved connection state and the activity that ran immediately before.
+
+2. **Branch the diagnostic on the signature.**
+   - `NullReferenceException` at the activity → branch 1; go to step 3.
+   - `Keyword not supported` / connection-string `ArgumentException` / SqlClient crash, post-migration → branch 2; go to step 4.
+   - `A database error occurred` wrapping a provider syntax error → branch 3; go to step 5.
+   - Connection error naming a non-existent database / SQL-looking text in the connection string → branch 4; go to step 6.
+   - `Timeout expired` → branch 5; go to step 7.
+   - Job exit `0xE0434352`, no activity-level exception → branch 6; go to step 8.
+   - Modification statement in `Execute Query`, or `Execute Non Query` result bound to a `DataTable` → branch 7; go to step 9.
+
+3. **Confirm branch 1 (null/out-of-scope connection).** In the workflow source, trace the variable bound to the query's `ExistingDbConnection` back to its producer:
+   - Confirm a `Connect to Database` or `Start Transaction` activity assigns that exact variable, and that it executes on the same path *before* `Execute Query` (not on a sibling `If`/`Catch` branch that was skipped).
+   - Confirm variable **scope**: the connection variable must be declared at or above the scope containing `Execute Query`. A connection created inside a nested `Sequence` is `Nothing` once execution leaves it.
+   - Confirm the connection was not already disposed — a `Connect` placed inside a scope/`Using` that closed before the query leaves an expired handle.
+
+4. **Confirm branch 2 (provider mismatch).** Check the project compatibility (`project.json` → `targetFramework`/`Windows` vs `Windows-Legacy`) and whether the failure began right after a migration. Inspect the `ProviderName` and `ConnectionString` on the `Connect`/`Execute Query` activity. SQL Server still on `System.Data.SqlClient` after a move to **Windows** is the canonical case; for MySQL, confirm the configured provider and whether the matching ODBC/managed driver is installed on the Robot host.
+
+5. **Confirm branch 3 (SQL syntax / concatenation).** Read the inner provider message — it names the syntax error and (often) the offending token. In the source, check whether `Sql` is a literal or built by string concatenation. If concatenation, log the fully resolved statement immediately before the activity (`Log Message Level=Info Message=$"SQL: {sqlText}"`) and rerun — the resolved text usually shows the broken quoting or a value injected mid-keyword.
+
+6. **Confirm branch 4 (query in the wrong property).** Inspect the activity properties: the `ConnectionString` field should contain `Server=...;Database=...;...` (or a provider DSN), and the `Sql` field should contain the `SELECT`. If the `SELECT` text is in the connection field, or the connection string has unbalanced quotes, branch 4 is confirmed.
+
+7. **Confirm branch 5 (timeout).** Read `TimeoutMS` (milliseconds; default `30000` = 30 s). Time the query independently against the DB (e.g., run it in the DB client) to learn its real duration, and check for blocking/locks at the failure time. Distinguish a query that is *legitimately* slow (needs a bigger timeout) from a *runaway* query (needs an index or a narrower result set) — see Resolution.
+
+8. **Confirm branch 6 (CLR crash).** `0xE0434352` is a process-level exit, so correlate the job's last activity (job logs) with the `Execute Query`. Estimate the result-set size the query would materialize, check whether the engine is Oracle returning a `REF CURSOR`, and read the `UiPath.Database.Activities` version. A multi-million-row `SELECT *` into a `DataTable` on a memory-constrained Robot is the prototypical trigger.
+
+9. **Confirm branch 7 (wrong activity).** Check the statement verb against the activity: `SELECT` → `Execute Query`; `INSERT`/`UPDATE`/`DELETE`/DDL → `Execute Non Query`. Check the output binding: an `Execute Query` output must be a `DataTable`; an `Execute Non Query` exposes an `AffectedRecords` output of type `Int32`.
+
+The root cause must name **which of the seven surfaces** the failure maps to, with the specific evidence: the inner provider exception, how the connection is supplied and scoped, the `Sql`/`ConnectionString`/`ProviderName`/`TimeoutMS` values, and (for branches 2/6) the project compatibility and package version. A generic "Execute Query failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Null / out-of-scope connection:**
+  - Ensure a `Connect to Database` (or `Start Transaction`) activity runs on the same path **before** `Execute Query`.
+  - Wire the connect activity's output variable to the query's `ExistingDbConnection` input — same variable, exact match.
+  - Declare the connection variable at a scope that encloses both activities. Do not create it inside a nested `Sequence` that `Execute Query` sits outside of.
+  - If the connection lives in a scope/`Using` that closes before the query, restructure so the query runs inside that scope, or open a connection that outlives it.
+
+- **Branch 2 — Driver provider mismatch after migration:**
+  - For SQL Server on a **Windows** (.NET 6+) project, switch the provider from `System.Data.SqlClient` to `Microsoft.Data.SqlClient` in the activity's provider/connection configuration, and adjust any connection-string keyword the new provider rejects.
+  - For MySQL, use the appropriate driver (e.g., `System.Data.Odbc` with the MySQL ODBC driver installed via the Windows ODBC Data Source Administrator on the Robot host, or the MySQL managed provider) and set the `ProviderName` accordingly.
+  - Verify the chosen provider's driver is actually installed on every Robot host that runs the process — not just the developer machine.
+
+- **Branch 3 — SQL syntax / unsafe concatenation:**
+  - Do **not** build SQL by concatenating variables into the statement (`"... WHERE id = " + myVar`) — it breaks parsing and is a SQL-injection risk.
+  - Use the activity's **Parameters** collection: reference a named parameter in the `Sql` (`SELECT * FROM t WHERE id = @id`) and map the UiPath variable to `@id` in the Parameters property. The provider handles quoting and typing.
+  - Fix any genuine syntax error reported by the inner provider message (the engine names the offending token).
+
+- **Branch 4 — Query in the wrong property:**
+  - Put the connection string (`Server=...;Database=...;...` or DSN) in the `ConnectionString` property, and the `SELECT` in the `Sql` / query property. They are different fields — do not cross them.
+  - Balance any quotes in the connection string; a stray quote truncates the parsed value and produces the misleading "database does not exist".
+
+- **Branch 5 — Command timeout exceeded:**
+  - If the query is *legitimately* long-running, raise `TimeoutMS` on the activity to a value above its worst observed duration. The property is in **milliseconds**: `60000` = 60 s (the default is `30000` = 30 s).
+  - If the query is a *runaway* (full scan, missing index), fix the root cause on the DB side — add an index, narrow the `WHERE`, or reduce the columns/rows — rather than only enlarging the timeout. Increasing the timeout on a runaway query just delays the same failure and ties up the Robot longer.
+
+- **Branch 6 — CLR crash (`0xE0434352`):**
+  - Bound the result set in SQL so it cannot exhaust memory: `SELECT TOP n ...` (SQL Server), `... WHERE ROWNUM <= n` / `FETCH FIRST n ROWS ONLY` (Oracle), `... LIMIT n` (MySQL/Postgres). Page through large data instead of materializing it all into one `DataTable`.
+  - For Oracle `REF CURSOR` output, verify the activity/version supports the cursor shape; update `UiPath.Database.Activities` to the latest stable version via **Manage Packages** if the crash is in the provider path.
+  - If the crash persists after bounding the data and updating the package, capture the Robot process dump and escalate — a reproducible `0xE0434352` inside the provider is a package/driver bug, not a workflow misconfiguration.
+
+- **Branch 7 — Wrong activity for the statement type:**
+  - Use `Execute Query` only for `SELECT` (output → `DataTable`).
+  - Use `Execute Non Query` for `INSERT`/`UPDATE`/`DELETE`/DDL (output → `AffectedRecords`, an `Int32` row count). Do not assign its result to a `DataTable`.
+  - For a stored procedure that both modifies and returns rows, pick the activity that matches the result you consume, and confirm the output type binding compiles.
+
+## Anti-patterns (what NOT to do)
+
+Common advice for Execute Query failures contains workarounds that hide bugs rather than fix them. The agent should NOT recommend any of these as a primary resolution.
+
+- **"Concatenate the variable straight into the SQL string."** (`"SELECT * FROM t WHERE id = " + myVar`) — breaks on quotes and non-string types, produces branch-3 syntax errors, and is a SQL-injection vulnerability. Always use named parameters (`@id`) mapped via the Parameters property.
+- **"Wrap Execute Query in a Try Catch and continue on error."** A bare catch that logs and swallows the exception turns a failed query into a silent empty `DataTable`; downstream activities then process zero rows as if the query succeeded, producing wrong results that are harder to diagnose than the original fault. Use Try-Catch only with a real recovery path (retry the transient connection, mark the queue item Failed, re-throw a domain exception).
+- **"Just set the timeout to a huge value."** Enlarging `TimeoutMS` is correct only for a query that is genuinely long-running. For a runaway/un-indexed query (branch 5) it masks the real problem, holds the Robot hostage for minutes, and the query still eventually fails or degrades the DB. Fix the query/index instead.
+- **"Update the package and hope."** Updating `UiPath.Database.Activities` resolves specific provider-path bugs (branch 2, branch 6), but is not a remedy for connection-wiring (branch 1), SQL syntax (branch 3), or property-misplacement (branch 4) failures. Confirm the branch first.
+
+## Prevention (cross-branch)
+
+- Always supply `Execute Query` from a `Connect to Database` / `Start Transaction` whose connection variable is scoped to enclose the query; verify the wiring at design time.
+- Parameterize every query with named parameters — never concatenate. This prevents branch 3 and closes the injection risk in one move.
+- After migrating a project from **Windows - Legacy** to **Windows**, audit every Database activity's `ProviderName`/`ConnectionString` and confirm the matching driver is installed on all Robot hosts (branch 2).
+- Bound result sets in SQL (`TOP`/`ROWNUM`/`FETCH FIRST`/`LIMIT`) for any query that could return large data, so a data-volume spike cannot crash the Robot (branch 6).
+- Choose the activity by statement verb up front — `Execute Query` for `SELECT`, `Execute Non Query` for modifications — and bind the output to the matching type (branch 7).
+- Pin and track the `UiPath.Database.Activities` version across environments so version-sensitive failures (branches 2, 6) reproduce consistently rather than differing dev-vs-prod.
+
+## Related
+
+- `Execute Non Query` failures share the connection (branch 1), provider (branch 2), and syntax (branch 3) surfaces — the diagnostic for those branches is identical; only the statement verb and output type differ (branch 7).
+- For job exit code `0xE0434352` originating outside a Database activity, treat it as a generic CLR-crash investigation (memory, native dependency, or package incompatibility) rather than a SQL problem.

package/skills/uipath-troubleshoot/references/activity-packages/database-activities/playbooks/start-transaction-failures.md

@@ -0,0 +1,94 @@
+---
+confidence: medium
+---
+
+# Start Transaction Failures
+
+## Context
+
+A `UiPath.Database.Activities` `Start Transaction` (`DatabaseTransaction`) activity is a **scope**: it opens a connection from a `ConnectionString` + `ProviderName`, begins a database transaction, runs the child activities in its body under that single transaction, and on normal scope exit **commits** — or, when an exception propagates out of the scope, **rolls back**. It outputs a `DatabaseConnection` that every child data activity (`Execute Query`, `Execute Non Query`, `Run Command`, bulk activities) must consume via its `ExistingDbConnection` input so the work is enrolled in the transaction.
+
+Start Transaction shares the connection/provider surface with `Connect to Database` (see [connect-to-database-failures.md](./connect-to-database-failures.md)) and the statement surface with the data activities (see [execute-query-failures.md](./execute-query-failures.md) / [execute-non-query-failures.md](./execute-non-query-failures.md)). What is **specific** to Start Transaction is the commit/rollback lifecycle and the requirement to thread its output connection into every child — that is where its distinct failure modes live. SQL-syntax, parameter, and command-timeout faults raised by a child statement are not transaction bugs; route those to the data-activity playbooks.
+
+What this looks like — Start Transaction faults surface as one of these signatures:
+
+- Job reports **Success**, but the database is unchanged (or partially changed) and a child activity's error never surfaced — the transaction did not roll back or re-raise. The most visible symptom is downstream logic proceeding on data that was never committed — branch 1.
+- Job reports **Success**, but **none** of the child activities ran — the transaction body was skipped with no error and no logs from inside the scope — branch 2.
+- `The type initializer for 'Microsoft.Data.SqlClient.SqlConnection' threw an exception` (or another provider type-initializer crash), or a design-time validation/compile error that the `DatabaseConnection` type is **missing / unresolvable**, appearing right after a **Windows - Legacy → Windows** migration — branch 3.
+- A child `Execute Query` / `Execute Non Query` faults with `Object reference not set to an instance of an object` (null connection) or an instant `Timeout expired`, or the writes succeed but are **not transactional** (committed independently, so a later failure cannot roll them back) — branch 4.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Silent success — a failing child does not roll back or re-raise.** On some package versions / configurations, when a child activity inside the scope hits a database error, the `Start Transaction` scope still completes as **Success** instead of rolling back and surfacing the fault. The child exception is absorbed by the scope, so the workflow neither rolls back the partial work nor registers a failure — downstream activities then operate on data that was never committed. This is the most dangerous branch because the job looks green.
+2. **Transaction scope skips its body (package-version bug).** A specific legacy build — notably `UiPath.Database.Activities` **v1.5.0** — fails to execute the activities inside the `Start Transaction` body at all. The scope enters and exits cleanly with **no error**, but every child database activity is skipped, so nothing is read or written. It is a package defect, not a workflow-configuration problem.
+3. **Post-migration provider / type breakage (Windows - Legacy → Windows).** After converting the project to the modern .NET runtime, the transaction's connection step crashes — a project still on `System.Data.SqlClient` throws a `Microsoft.Data.SqlClient` type-initializer / execution error — and/or the `DatabaseConnection` variable type appears **missing or unresolvable** at design time (broken type reference after the upgrade). Same provider surface as the connect/query playbooks, reached through the transaction scope.
+4. **Output connection not propagated to child activities.** The scope produces a `DatabaseConnection`, but a child `Execute Query` / `Execute Non Query` does not consume it: it is left with an empty/`Nothing` connection (→ null-reference, or instant `Timeout expired` while it waits on an unopened/throwaway connection), or it carries its **own** inline `ConnectionString` + `ProviderName` and opens a separate connection — running **outside** the transaction so its writes auto-commit and cannot be rolled back with the rest. Either way the transaction's guarantee is lost.
+
+What to look for:
+
+- **Job final state vs. database state** — a `Success` job with no committed data (branch 1) or with no child-activity log lines at all (branch 2). Branch 1 has child error evidence that was swallowed; branch 2 has an empty, errorless scope.
+- **`UiPath.Database.Activities` package version** — from `project.json`. `v1.5.0` is the known body-skip build (branch 2); branches 1 and 3 are also version- and runtime-sensitive.
+- **Project compatibility** — `Windows` vs `Windows - Legacy`, and whether the failure began right after a migration. Load-bearing for branch 3.
+- **Child connection wiring** — for every data activity inside the scope, whether `ExistingDbConnection` is bound to the **scope's** output `DatabaseConnection`, or whether the child carries its own inline connection. Load-bearing for branch 4.
+- **Whether child errors are handled** — the presence (or absence) of a `Try Catch` / `Throw` around the in-scope statements, which determines whether a child fault rolls the transaction back (branch 1).
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Establish job state vs. expected database effect.** From `uip or jobs get <job-key> --output json` → `State` and `Info`, and `uip or jobs logs <key> --output json`: did the job report `Success` or `Faulted`? Did the expected rows actually commit? List the activity log lines emitted from inside the scope. A green job with no committed data — or with no in-scope activity logs — is the primary signal that separates the transaction-specific branches (1, 2) from a normal child-statement fault.
+2. **Read the package version and project compatibility.** From `project.json`: the pinned `UiPath.Database.Activities` version and `targetFramework` (`Windows` vs `Windows-Legacy`). `v1.5.0` → suspect branch 2; a recent migration to `Windows` → suspect branch 3.
+3. **Branch the diagnostic on the signature.**
+   - `Success` with a swallowed child error and no rollback → branch 1; go to step 4.
+   - `Success` with an empty scope (no child ran) on `v1.5.0` → branch 2; go to step 5.
+   - SqlClient type-initializer crash, or `DatabaseConnection` type unresolvable, post-migration → branch 3; go to step 6.
+   - Child null-connection / instant timeout, or non-transactional writes → branch 4; go to step 7.
+4. **Confirm branch 1 (silent success / no rollback).** In the workflow source, check whether the in-scope statements are wrapped so a child fault propagates out of the scope. If a child clearly errored (inner provider exception in the logs) yet the job is `Success` and the data is unchanged/partial, the scope absorbed the fault instead of rolling back and re-raising — branch 1 confirmed.
+5. **Confirm branch 2 (scope skips body).** Confirm the package is `v1.5.0` (or another build with the documented body-skip defect) and that the scope produced **no** in-scope activity logs and **no** error. A clean, instantaneous, empty transaction on that version confirms the package bug rather than a config error.
+6. **Confirm branch 3 (post-migration provider / type).** Confirm the project is now `Windows` and the failure began at migration. A `Microsoft.Data.SqlClient` type-initializer / SqlClient error on connect, or a design-time error that `DatabaseConnection` (or the activity) is unresolvable, confirms the branch. Cross-check [connect-to-database-failures.md](./connect-to-database-failures.md) branch 4 and [execute-query-failures.md](./execute-query-failures.md) branch 2 — the provider surface is shared.
+7. **Confirm branch 4 (connection not propagated).** For each child data activity in the scope, read whether `ExistingDbConnection` is the scope's output variable. An empty connection input (→ `Object reference not set` / instant `Timeout expired`) or a child carrying its own inline `ConnectionString`/`ProviderName` (→ writes that committed outside the transaction) confirms the branch.
+
+The root cause must name **which of the four surfaces** the failure maps to, with the specific evidence: the job state vs. committed data, the package version, the project compatibility, and the child connection wiring. A generic "the transaction failed" is not a confirmed finding — and a child SQL-syntax or command-timeout error is a data-activity fault, not a transaction fault.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Silent success / no rollback:**
+  - Wrap the in-scope database statements in a `Try Catch`. In the catch, **re-raise** with a `Throw` (or throw a domain exception) so the fault propagates out of the `Start Transaction` scope and triggers the rollback — do not log-and-continue.
+  - If a multi-step unit must be all-or-nothing, ensure any child failure leaves the scope via an exception so the transaction rolls back as a whole; only commit (let the scope exit normally) when every step succeeded.
+  - For broad coverage across processes, add a **Global Exception Handler** so hidden database exceptions are caught and routed rather than absorbed.
+
+- **Branch 2 — Scope skips its body (package bug):**
+  - Open **Manage Packages** in Studio and move `UiPath.Database.Activities` off the defective build: upgrade to the latest stable (**v1.7.1** or newer), or downgrade to a known-good older release (**v1.4.0**). This is a package-version fix, not a workflow change.
+
+- **Branch 3 — Post-migration provider / type breakage:**
+  - For SQL Server on a **Windows** (.NET) project, change the provider from `System.Data.SqlClient` to `Microsoft.Data.SqlClient` on the transaction's connection configuration, and adjust any rejected connection-string keyword (same fix as [execute-query-failures.md](./execute-query-failures.md) branch 2).
+  - For MySQL, switch the configuration to `System.Data.Odbc` with the MySQL ODBC driver installed on every Robot host.
+  - If the `DatabaseConnection` type (or the activity) shows as missing/unresolvable after the upgrade, close Studio and clear the local cache at `%LOCALAPPDATA%\UiPath\Studio\Cache`, then reopen so the package types re-resolve.
+
+- **Branch 4 — Output connection not propagated:**
+  - Pass the `Start Transaction` output `DatabaseConnection` into the **`ExistingDbConnection`** (Existing Connection) property of **every** child data activity. Do not give the child its own inline `ConnectionString` + `ProviderName` — that opens a separate connection that runs outside the transaction.
+  - Verify the connection variable is declared at the scope of the `Start Transaction` body so every child can see it (a connection scoped to an inner `Sequence` is `Nothing` for siblings — see [execute-query-failures.md](./execute-query-failures.md) branch 1).
+
+## Anti-patterns (what NOT to do)
+
+- **"Wrap each in-scope query in a Try Catch that logs and continues."** A bare catch that swallows the child exception is exactly what produces branch 1: the scope completes `Success`, nothing rolls back, and downstream logic runs on uncommitted/partial data. Catch only to **re-raise** (or to run a real recovery path), so the transaction still rolls back on failure.
+- **"Give each in-scope activity its own connection string so they're independent."** Per-child inline connections run **outside** the transaction (branch 4) — their writes auto-commit and cannot be rolled back with the batch, defeating the entire point of `Start Transaction`. Thread the scope's `DatabaseConnection` into every child instead.
+- **"Add a Delay or a Retry Scope around the whole transaction to make it stick."** Neither addresses a body-skip package bug (branch 2 — fix the version) or a swallowed-rollback (branch 1 — fix the exception flow); they only hide the symptom and hold locks longer.
+- **"Downgrade/upgrade the package on a hunch."** A version change is the fix only for the documented body-skip defect (branch 2). For branches 1, 3, and 4 it changes nothing — confirm the branch from evidence first.
+
+## Prevention (cross-branch)
+
+- Let child faults **propagate** out of the `Start Transaction` scope (re-throw in any in-scope catch) so commit happens only on full success and any failure rolls the whole unit back.
+- Thread the scope's output `DatabaseConnection` into the `ExistingDbConnection` of every child activity at design time; never let an in-scope activity open its own connection.
+- Pin and track the `UiPath.Database.Activities` version across environments and avoid known-defective builds (e.g. v1.5.0); validate the transaction body actually executes after any version change.
+- After migrating a project from **Windows - Legacy** to **Windows**, set the provider explicitly (`Microsoft.Data.SqlClient` / `System.Data.Odbc`), re-validate every Database activity, and clear the Studio cache if package types fail to resolve.
+- Keep transactions short and commit promptly to limit lock duration; command-timeout and runaway-query tuning inside the transaction follow [execute-query-failures.md](./execute-query-failures.md) branch 5.
+
+## Related
+
+- [connect-to-database-failures.md](./connect-to-database-failures.md) — the non-transactional connection-open surface (connection string, provider registration/bitness, file lock, provider init after migration); branch 3 here shares its provider-init fix.
+- [execute-query-failures.md](./execute-query-failures.md) — child-statement faults inside the scope (null/out-of-scope connection, provider mismatch, SQL syntax, command timeout); a child SQL/timeout error is a query fault, not a transaction fault.
+- [execute-non-query-failures.md](./execute-non-query-failures.md) — modification-statement faults (output-parameter sizing, parameter mapping, empty `Sql`, driver load) raised by an in-scope `Execute Non Query`.
+- [`../overview.md`](../overview.md) — the package connection model (Connect / Start Transaction → `DatabaseConnection` → data activities → commit/rollback or Disconnect).

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

@@ -0,0 +1,10 @@
+# Database Activities Presentation Rules
+
+- **Activities** — use the display name (e.g., "Execute Query", "Execute Non Query", "Connect to Database", "Start Transaction", "Run Command"), not the fully qualified class name (e.g., `UiPath.Database.Activities.ExecuteQuery`)
+- **Databases / connections** — refer to the database by its server + database name from the connection string (e.g., "the `SALES` database on `db-prod-01`"), not by the variable holding the `DatabaseConnection`
+- **SQL statements** — refer to the statement by what it does (e.g., "the `SELECT` against `Orders`"), and quote the relevant SQL fragment; do not refer to it by the variable holding the query text
+- **Parameters** — refer to query parameters by their named placeholder as written in the SQL (e.g., "`@customerId`"), and recommend the `Parameters` collection over string concatenation
+- **Providers** — name the ADO.NET provider exactly as configured (e.g., `Microsoft.Data.SqlClient`, `System.Data.SqlClient`, `System.Data.Odbc`), since connection-string syntax and error text depend on it
+- **Timeouts** — state timeout values in **milliseconds** with the second-equivalent in parentheses (e.g., "`TimeoutMS` 60000 (60 s)"), because the property is `TimeoutMS`, not a seconds-based field
+- **Project compatibility** — refer to project type as **Windows** or **Windows - Legacy** (the exact Studio labels), since the distinction drives provider/driver behaviour
+- **Errors** — quote the **inner** provider error (e.g., `Incorrect syntax near ')'`, `ORA-00900`, `Keyword not supported: 'Provider'`), not only the UiPath wrapper `Execute Query: A database error occurred`

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

@@ -0,0 +1,10 @@
+# Database Activities Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and evidence-gathering prerequisites for Database Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Execute Query Failures | Medium | `Execute Query` faults across seven surfaces: null/out-of-scope `DatabaseConnection`, post-migration provider mismatch (`Keyword not supported`), SQL syntax / unsafe concatenation (`A database error occurred`), query text pasted into the connection-string field, `TimeoutMS` exceeded (`Timeout expired`), `0xE0434352` CLR crash (oversized result set / Oracle ref cursor / stale package), and wrong activity for the statement type (Execute Query vs Execute Non Query). Includes anti-patterns and cross-branch prevention. | [execute-query-failures.md](./playbooks/execute-query-failures.md) |
+| Connect to Database Failures (Excel / Access via OLE DB / ODBC) | Medium | `Connect to Database` faults across four surfaces: malformed connection string (`Invalid connection string` / `ArgumentException`), ACE/Jet provider not registered or 32-vs-64-bit mismatch (`provider is not registered on the local machine`), file lock (`used by another process`), and provider init / wrong `ProviderName` after Windows-Legacy → Windows migration (`type initializer for 'Microsoft.Data.SqlClient.SqlConnection'`). Centered on the Excel-as-a-database pattern. | [connect-to-database-failures.md](./playbooks/connect-to-database-failures.md) |
+| Start Transaction Failures | Medium | `Start Transaction` (`DatabaseTransaction`) scope faults across four transaction-specific surfaces: silent success — a failing child neither rolls back nor re-raises so the job looks green on uncommitted data; scope skips its body with no error on the defective package build (v1.5.0); post-migration provider crash / unresolvable `DatabaseConnection` type after Windows-Legacy → Windows; and the scope's output `DatabaseConnection` not propagated to child `ExistingDbConnection` (null/instant-timeout, or writes that committed outside the transaction). Child SQL/timeout faults route to the data-activity playbooks. | [start-transaction-failures.md](./playbooks/start-transaction-failures.md) |
+| Execute Non Query Failures | Medium | `Execute Non Query` (INSERT/UPDATE/DELETE/DDL/stored proc) faults across four surfaces: stored-proc output parameter with `Size = 0` over ODBC (`The Size property has an invalid size of 0`), unsafe SQL construction / parameter mapping / wrong type or DataTable-into-column (`A database error occurred`), empty `Sql` (`CommandText property has not been initialized`), and driver/client library not loadable (`Failed to load library (ErrorCode: 126)`). Covers the parameterize + Bulk Insert/Update guidance and the don't-use-for-SELECT rule. | [execute-non-query-failures.md](./playbooks/execute-non-query-failures.md) |

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

@@ -4,16 +4,25 @@
 
 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.Excel.Activities.Business.InvokeVBAX`, `UiPath.Excel.Activities.ExcelLookUpRange`, `UiPath.Excel.Activities.LookUpRangeX`). Classic Interop activities (inside an `Excel Application Scope`) and modern `*X` activities (inside `Use Excel File` / `Excel Process Scope`) share display names but run different code paths — treat them as different. `Invoke VBA` only exists on the modern (COM) surface; `Lookup Range` exists on both (classic `ExcelLookUpRange`, modern `LookUpRangeX`).
-- **Workbook** — the workbook path in evidence matches the file the user is asking about. `Invoke VBA` operates on the workbook open inside the surrounding `Excel Process Scope` — different scope = different workbook = unrelated data.
+- **Activity** — the faulted activity's namespace and class match the reported failure (e.g., `UiPath.Excel.Activities.Business.ReadRangeX`, `UiPath.Excel.Activities.ExcelReadRange`, `UiPath.Excel.Activities.Business.InvokeVBAX`, `UiPath.Excel.Activities.ExcelLookUpRange`, `UiPath.Excel.Activities.LookUpRangeX`). Classic Interop activities (inside an `Excel Application Scope`) and modern `*X` activities (inside `Use Excel File` / `Excel Process Scope`) share display names but run different code paths and surface different exception wrappings — treat them as different. `Invoke VBA` only exists on the modern (COM) surface; `Lookup Range` exists on both (classic `ExcelLookUpRange`, modern `LookUpRangeX`).
+- **Workbook path** — the workbook path in evidence matches the file the user is asking about. Casing, drive-letter mapping, and UNC vs. mapped-drive forms can all differ between a user's mental model and the runtime path. `Invoke VBA` operates on the workbook open inside the surrounding `Excel Process Scope` — different scope = different workbook = unrelated data. Don't substitute a similar path.
+- **Sheet name** — the configured `SheetName` matches the one the user reports. Sheet names are surfaced case-sensitively by the OpenXML provider; Excel COM is more forgiving.
 - **Code file** — the `CodeFilePath` in evidence resolves to the macro source the user is asking about. A `.txt`/`.vba`/`.bas` file path that no longer exists on the robot machine, or a stale path checked into source control, is a different file than the one the user has open locally.
 - **Entry method** — the `EntryMethodName` in evidence matches the macro the user reports calling. Don't substitute a similarly-named macro.
-- **Robot / machine identity** — the robot account and the machine where Excel installed match the one the user reports. Excel security settings (Trust Center, Trust access to VBA project) are per-user-per-machine, so evidence from a different host is not transferable.
+- **Workflow file** — if the project contains multiple workflows, the error originates from the `.xaml` / `.cs` the user is asking about, not a different workflow that happens to use the same activity.
+- **Robot / machine identity** — the robot account and the machine where Excel is installed match the one the user reports. Excel install state, orphan `EXCEL.EXE` processes, AV/EDR posture, and security settings (Trust Center, Trust access to VBA project) are per-host (and per-user), so evidence from a different host is not transferable.
 - **Office version** — the Excel/Office version installed on the robot machine matches the one the user reports. Multiple Office versions on the same host produce COM dispatcher ambiguity unrelated to a single-version user's experience.
-- **Timestamp** — the failure occurred during the time window the user reported. Load-bearing for COM-interop investigations (transient `0x80010100` errors may not reproduce on demand) and for Trust Center investigations (the setting may have been changed since).
+- **Timestamp** — the failure occurred during the time window the user reported. Load-bearing for file-lock investigations (the locking process may no longer exist by the time you check), COM-interop investigations (transient `0x80010100` errors may not reproduce on demand), and Trust Center investigations (the setting may have been 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. **Container scope** — capture whether the activity ran inside `Excel Application Scope` (legacy) or `Use Excel File` (modern). The scope determines which provider is in use, whether Excel UI is visible, and whether file acquisition uses COM or OpenXML. Read the workflow source — the scope is not always visible in the runtime error string.
+2. **Workbook provider** — for `Use Excel File`, capture whether the activity ran on the OpenXML provider or fell back to Excel COM. The `Read Formatting`, `Edit Password`, and macro-related properties force COM. Provider in use changes the exception wording and the set of supported features.
+3. **Robot Execution.log** — `%LocalAppData%\UiPath\Logs\Execution.log` on the host. Captures the activity-level log lines around the failure; often shows the workbook open / close pair so the lock window is observable.
+4. **Host-side process state** — for file-acquisition and COM failures, the host's process list at failure time is the authoritative evidence. If the user can capture `Get-Process EXCEL` or `handle.exe -a <path>` (Sysinternals) at the next failure, those are the strongest possible signals.
+
 ### Invoke VBA
 
 1. **Workflow source** — read the `InvokeVBAX` activity node from the surrounding `.xaml` to capture the literal values of `CodeFilePath`, `EntryMethodName`, and the expression bound to `EntryMethodParameters`. Property panel summaries truncate; the XAML is authoritative.
@@ -34,9 +43,19 @@ If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy.
 
 ## Testing Prerequisites
 
+When testing hypotheses for Excel Activities issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — class name and display name from the workflow source or stack trace. Distinguish modern (`*X` / `ReadRangeX`) from legacy (`ReadRange`) — they belong to different activity families within the same NuGet package.
+2. **Scope** — `Excel Application Scope` vs. `Use Excel File`. Determines provider and acquisition semantics.
+3. **Workbook reference** — the configured workbook path expression (literal vs. variable), the resolved path at runtime if available, and the host filesystem on which the path is meant to resolve.
+4. **Activity input properties** — every input the activity uses to address its target, from workflow source: `SheetName`, `Range`, `AddHeaders`, `PreserveFormat`, `Visible`, `EditPassword`, `ReadOnly`. The playbook will name the subset that matters.
+5. **Host context** — host machine name, Excel version installed (or whether Excel is installed at all), Robot user that owned the failing job's session, AV/EDR product running on the host.
+6. **Job run timestamp** — exact time the activity executed. Required for matching host-side process snapshots and for AV/EDR log correlation.
+7. **Package version** — `UiPath.Excel.Activities` version from `project.json`. Exception messages, default provider, and the supported subset of OpenXML features have shifted across versions; version-specific bugs are documented in playbooks as they're discovered.
+
 ### Invoke VBA
 
-When testing hypotheses for `Invoke VBA` issues, gather and verify these before drawing conclusions:
+When testing hypotheses for `Invoke VBA` issues, also gather and verify these:
 
 1. **Activity identity** — confirm the faulted activity is `UiPath.Excel.Activities.Business.InvokeVBAX` (display name "Invoke VBA") and not a generic `Excel.Macros` or `Invoke Macro` activity, which run different code paths.
 2. **Macro source file path** — exact path bound to `CodeFilePath`, resolved against the robot's working directory at job run time (relative paths are resolved against the project folder, not the workbook folder).
@@ -44,13 +63,12 @@ When testing hypotheses for `Invoke VBA` issues, gather and verify these before
 4. **Entry method name and signature** — exact `EntryMethodName` string, exact `Sub`/`Function` declaration in the code file (name, parameter count, parameter types). VBA is case-insensitive but parentheses and trailing whitespace are not.
 5. **Parameter expression** — the expression bound to `EntryMethodParameters`. Confirm it evaluates to an `IEnumerable<Object>` (typically a `New Object() {...}` array, not a raw string or single value).
 6. **Excel Process Scope properties** — `Visible` setting, `ShowOnPrompt` / dialog handling, workbook path, password (if any), and whether the scope runs with `WorkbookPath` set or against an already-open workbook.
-7. **Trust Center setting** — captured directly from the robot machine under the running user account. The setting is not visible in Orchestrator and cannot be inferred from job logs alone — the user (or someone with desktop access on the host) has to check it.
-8. **Package version** — `UiPath.Excel.Activities` version. The exception messages produced by `InvokeVBAX` have shifted across major versions (notably the 2.20 → 2.22 and 6.x rewrites).
-9. **Office version and bitness** — the exact Excel version installed on the robot machine and whether it is 32-bit or 64-bit. Mismatch with robot bitness is a known cause of COM dispatcher errors.
+7. **Trust Center setting** — captured directly from the robot machine under the running user account. Not visible in Orchestrator and not inferable from job logs alone — the user (or someone with desktop access on the host) has to check it.
+8. **Office version and bitness** — the exact Excel version installed on the robot machine and whether it is 32-bit or 64-bit. Mismatch with robot bitness is a known cause of COM dispatcher errors.
 
 ### Lookup Range
 
-When testing hypotheses for `Lookup Range` issues, gather and verify these before drawing conclusions:
+When testing hypotheses for `Lookup Range` issues, also gather and verify these:
 
 1. **Activity surface** — confirm classic `UiPath.Excel.Activities.ExcelLookUpRange` (Interop, inside `Excel Application Scope`) vs modern `UiPath.Excel.Activities.LookUpRangeX` (inside `Use Excel File` / `Excel Process Scope`). The Excel-not-installed failure is most acute on the classic Interop surface.
 2. **Range / Value / SheetName** — the literal `Range` (blank vs `""` vs A1 reference), the search `Value` expression and its .NET type, and the `SheetName`. These drive the invalid-range, null-reference, and active-filter hypotheses.

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

@@ -1,6 +1,17 @@
 # Excel Activities
 
-Activities from the `UiPath.Excel.Activities` package for automating Microsoft Excel on Windows. Two execution surfaces coexist: modern Excel-scope activities that operate inside an `Excel Process Scope` and drive a real Excel.exe instance via COM interop, and legacy workbook activities that read/write `.xlsx` files directly through OpenXML without Excel installed. `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) is COM-only — it requires Excel.exe and a workbook handle.
+Activities from the `UiPath.Excel.Activities` package for automating Microsoft Excel workbooks on Windows. The package supports two runtime providers and two container shapes; failure surfaces differ across them. Modern Excel-scope activities run inside an `Excel Process Scope` / `Use Excel File` and either drive a real Excel.exe instance via COM interop or read/write through OpenXML; legacy workbook activities and `Excel Application Scope` use COM (Excel installed) or OpenXML file access. `Invoke VBA` (`UiPath.Excel.Activities.Business.InvokeVBAX`) is COM-only — it requires Excel.exe and a workbook handle.
+
+> **Scope** — this package is the desktop Excel surface (`UiPath.Excel.Activities`). Cloud Excel via Microsoft Graph lives in `UiPath.MicrosoftOffice365.Activities` and is documented under [`o365-activities/`](../o365-activities/overview.md).
+
+## How Execution Works
+
+A Read Range / Write Range / Append Range / Delete Range / sheet-op activity executes inside one of two scopes:
+
+1. **Excel Application Scope** (legacy) — opens the workbook through Microsoft Excel via COM interop. Requires Excel installed on the host. Holds the workbook open for the duration of the scope. Activities inside the scope inherit the open workbook reference.
+2. **Use Excel File** (modern, same NuGet package) — opens the workbook with the OpenXML provider by default; falls back to Excel COM when the file requires Excel features the OpenXML provider does not support (or when `Read Formatting` / similar properties force COM). Does not require Excel installed when only OpenXML features are used.
+
+Failures originate at one of four layers: file resolution (path / share / permissions), file acquisition (lock / corruption), provider parsing (sheet / range / cell address), or post-processing inside the activity (cell-type conversion, formula evaluation).
 
 ## How Invoke VBA Executes
 
@@ -16,25 +27,55 @@ Failures can originate at any layer — Excel security policy (step 3), code fil
 
 ## Key Activities
 
+### Range read / write / delete
+
+- **Read Range** (`ReadRange`, modern `ExcelReadRange`) — read a rectangular range from a worksheet into a `DataTable`. Accepts a sheet name plus an A1-notation range (empty range = used range).
+- **Read Cell** / **Read Cell Formula** — read a single cell value or its formula text.
+- **Read Column** / **Read Row** — read a single column or row into an array.
+- **Write Range** / **Write Cell** / **Append Range** — write a `DataTable`, value, or appended rows back to a worksheet. Subject to the same file-acquisition and sheet-resolution failures as the read family.
+- **Delete Range** (`DeleteRange`, modern `DeleteRangeX`) — remove a range and shift surrounding cells. Sensitive to `ShiftCells` / `ShiftOption` interaction with merged cells and Excel Tables.
+
+### Sheet / workbook / filtering
+
+- **Get Workbook Sheets** — enumerate sheet names in a workbook.
+- **Insert Sheet** / **Delete Sheet** / **Rename Sheet** / **Copy Sheet** — sheet-level operations.
+- **Filter Range** / **Pivot Range** / **Sort Range** — operations on a configured range; share the sheet- and range-resolution failure surface with the read family.
+
+### Macros and lookup
+
 - **Invoke VBA** (`InvokeVBAX`, display name "Invoke VBA") — execute a VBA macro stored in an external code file against the workbook currently open in the parent `Excel Process Scope`. Properties: `CodeFilePath` (path to `.txt`/`.vba`/`.bas` containing the macro source), `EntryMethodName` (name of the `Sub` or `Function` to invoke), `EntryMethodParameters` (`IEnumerable<Object>` of arguments), `Output` (return value when `EntryMethodName` points to a `Function`).
-- **Lookup Range** — find the cell address of a value within a worksheet range. Two surfaces: classic `UiPath.Excel.Activities.ExcelLookUpRange` (inside an `Excel Application Scope`, **Excel Interop / COM only**) and modern `UiPath.Excel.Activities.LookUpRangeX` (inside a `Use Excel File` / `Excel Process Scope`). Properties: `Range` (A1 range to search; leave **blank** — not `""` — to search the whole used range), `Value` (the value to find), `SheetName` (target sheet), `Output` (the matched cell address). Searches only *visible* cells, so active AutoFilters change the result.
+- **Execute Macro** (`ExecuteMacro`, modern "Run Spreadsheet Macro") — run a macro already present in the workbook by name. COM-only.
+- **Lookup Range** — find the cell address of a value within a worksheet range. Two surfaces: classic `UiPath.Excel.Activities.ExcelLookUpRange` (inside an `Excel Application Scope`, **Excel Interop / COM only**) and modern `UiPath.Excel.Activities.LookUpRangeX` (inside a `Use Excel File` / `Excel Process Scope`). Properties: `Range` (A1 range to search; leave **blank** — not `""` — to search the whole used range), `Value`, `SheetName`, `Output` (the matched cell address). Searches only *visible* cells, so active AutoFilters change the result.
 
 ## Common Failure Patterns
 
-- **Trust access to VBA project denied** — `Invoke VBA` faults the first time it tries to inject a module because Excel's "Trust access to the VBA project object model" setting is disabled. Surfaces as `Programmatic access to Visual Basic Project is not trusted` or a wrapped variant. The error is a security-policy block, not a code defect.
-- **Macro source file unreadable or malformed** — `Invoke VBA` faults reading or compiling the macro source. Surfaces as `Cannot run the macro`, `Compile error`, `Syntax error`, or `Sub or Function not defined`. Causes: code not wrapped in a `Sub`/`Function` block, non-UTF-8 encoding with hidden BOM/control characters (common when the file was generated inside Studio), missing or wrong `CodeFilePath`, code authored in an `.xlsm` rather than an external text file.
-- **Entry method name mismatch** — `Invoke VBA` faults with `Cannot run the macro '<name>'. The macro may not be available in this workbook` or `Sub or Function not defined` because `EntryMethodName` does not match a `Sub`/`Function` declared in the code file. Causes: typo, case mismatch (VBA identifiers are case-insensitive in source but UiPath passes the string through to `Application.Run`, which has been observed to reject case-mismatched names in some Excel versions), parentheses appended to the name (`MyMacro()` instead of `MyMacro`), or the macro is nested inside another `Sub`.
-- **Parameter type or shape mismatch** — `Invoke VBA` faults marshaling `EntryMethodParameters` into the COM call. Surfaces as `Type mismatch`, `Wrong number of arguments or invalid property assignment`, or a Studio freeze during property edit. Causes: `EntryMethodParameters` not an `IEnumerable<Object>` (e.g., a raw `String` or `Object` typed directly into the property panel), wrong arity (count mismatches the macro signature), or values typed inline in the property window instead of built via an `Assign` activity.
-- **COM interop with Excel failed** — `Invoke VBA` (or the surrounding Excel activity) faults with an HRESULT from the COM layer. The most common is `0x80010100 RPC_E_SYS_CALL_FAILED` ("The system call failed"). Causes: Excel busy with a blocking modal dialog (license prompt, recover-unsaved-files banner, macro-warning bar), Excel.exe hung, multiple Office versions installed, or a 32-bit/64-bit Office mismatch with the robot process.
+### Read / Write / Delete Range
+
+- **File-locked** — `System.IO.IOException: The process cannot access the file '<path>' because it is being used by another process.` Workbook held open by another process (user-opened Excel UI, orphan `EXCEL.EXE` from a prior job, lock from a different host on a network share). Affects every activity that opens the workbook (Read Range, Write Range, Delete Range, Excel Application Scope, Use Excel File).
+- **Sheet not found** — `BusinessRuleException: The sheet with the name '<name>' does not exist` (wording varies slightly by package version). Configured `SheetName` does not match any sheet in the workbook — typo, case-sensitivity on the OpenXML provider, sheet renamed or deleted upstream, leading/trailing whitespace. Affects every range-addressed activity.
+- **File not found** — `System.IO.FileNotFoundException: Could not find file '<path>'` or `System.IO.DirectoryNotFoundException`. Workbook path does not resolve — file moved or deleted, UNC share unreachable, relative path resolved against the wrong working directory, drive letter not mapped under the Robot's session.
+- **Null reference / target-invocation** — `System.NullReferenceException` or `System.Reflection.TargetInvocationException` surfacing from inside the activity. Workbook contains content the active provider cannot parse — sensitivity labels (Microsoft Purview / Azure Information Protection), unsupported macros or embedded objects under the OpenXML provider, broken named ranges, formula references to deleted sheets, or (on Write Range) an uninitialized `DataTable`. Often masked by a generic wrapper exception with no specific cell pointer.
+
+### Invoke VBA
+
+- **Trust access to VBA project denied** — `Invoke VBA` faults the first time it tries to inject a module because Excel's "Trust access to the VBA project object model" setting is disabled. Surfaces as `Programmatic access to Visual Basic Project is not trusted` or a wrapped variant. A security-policy block, not a code defect.
+- **Macro source file unreadable or malformed** — faults reading or compiling the macro source. Surfaces as `Cannot run the macro`, `Compile error`, `Syntax error`, or `Sub or Function not defined`. Causes: code not wrapped in a `Sub`/`Function` block, non-UTF-8 encoding with hidden BOM/control characters (common when the file was generated inside Studio), missing or wrong `CodeFilePath`, code authored in an `.xlsm` rather than an external text file.
+- **Entry method name mismatch** — `Cannot run the macro '<name>'. The macro may not be available in this workbook` or `Sub or Function not defined` because `EntryMethodName` does not match a `Sub`/`Function` declared in the code file. Causes: typo, case mismatch, parentheses appended to the name (`MyMacro()` instead of `MyMacro`), or the macro nested inside another `Sub`.
+- **Parameter type or shape mismatch** — faults marshaling `EntryMethodParameters` into the COM call. Surfaces as `Type mismatch`, `Wrong number of arguments or invalid property assignment`, or a Studio freeze during property edit. Causes: not an `IEnumerable<Object>` (e.g., a raw `String` typed into the property panel), wrong arity, or values typed inline instead of built via an `Assign`.
+- **COM interop with Excel failed** — faults with an HRESULT from the COM layer, most commonly `0x80010100 RPC_E_SYS_CALL_FAILED` ("The system call failed"). Causes: Excel busy with a blocking modal dialog (license prompt, recover-unsaved-files banner, macro-warning bar), Excel.exe hung, multiple Office versions installed, or a 32-bit/64-bit Office mismatch with the robot process.
+
+### Execute Macro
+
+- **Macro fault / hang** — `COMException` with `0x80020009 DISP_E_EXCEPTION`, `0x800AC472`, or `0x80010108 RPC_E_DISCONNECTED`; or a job hang with no exception when the macro surfaces a modal dialog. Causes: macro name absent from the workbook, a VBA error inside the macro, the macro tearing down Excel (`Workbooks.Close` / `Application.Quit`), Trust Center policy disabling macros on the Robot host, an STA apartment violation, or a missing add-in / ActiveX dependency.
 
 ### Lookup Range
 
 - **Excel not installed / Interop init failure** — classic `Lookup Range` launches Excel.exe via the Interop API and faults at startup on a host with no Excel. Surfaces as `Excel is not installed`, `REGDB_E_CLASSNOTREG` (`80040154`), or `Could not load ... Microsoft.Office.Interop.Excel`. Migration target on Excel-less hosts: Workbook `Read Range` (OpenXML) + `Lookup Data Table`.
-- **Silent miss from active filters** — `Lookup Range` searches only visible cells, so active AutoFilters/column filters that hide the target row make it return null/empty with no error. A downstream null fault is the first visible symptom.
-- **Workbook locked / file in use** — opening the workbook faults with `The process cannot access the file because it is being used by another process` / `locked for editing`. Causes: file open interactively, an orphaned `EXCEL.EXE` holding the handle, a concurrent job, or a sync/AV client. Distinct from the COM `0x80010100` dispatcher failure above.
+- **Silent miss from active filters** — searches only visible cells, so active AutoFilters/column filters that hide the target row make it return null/empty with no error. A downstream null fault is the first visible symptom.
+- **Workbook locked / file in use** — opening the workbook faults with `being used by another process` / `locked for editing`. Causes: file open interactively, an orphaned `EXCEL.EXE` holding the handle, a concurrent job, or a sync/AV client. Distinct from the COM `0x80010100` dispatcher failure above.
 - **Object reference not set (sheet/range missing or no scope)** — `NullReferenceException` when the `SheetName` does not exist (typo/rename/case), a named range/table is undefined, or the activity runs outside an `Excel Application Scope` / `Use Excel File` so there is no workbook context.
 - **Invalid range syntax or value misconfiguration** — `Range` set to an empty-string `""` instead of left blank (whole-sheet search is *blank*, not `""`), a malformed A1 reference, unescaped wildcards (`*`/`?`/`~`) in the search `Value`, or a type mismatch (text-vs-number, stray whitespace) that makes a present value fail to match.
-- **Silent miss against a formula cell** — the search target is the *computed* result of an Excel formula and the Interop read can fail or read an unrefreshed value. `Lookup Range` returns null/wrong even though the displayed cell text matches the search value. Common with volatile formulas, cross-sheet / external references, and add-in-dependent calculations. The fix is to either freeze the cell to a static value (`Copy > Paste Special > Values`) or move off Interop to the Workbook `Read Range` + `Lookup Data Table` path, which reads cached values rather than re-evaluating.
+- **Silent miss against a formula cell** — the search target is the *computed* result of an Excel formula and the Interop read can fail or read an unrefreshed value. Returns null/wrong even though the displayed cell text matches. Common with volatile formulas, cross-sheet / external references, and add-in-dependent calculations. Fix: freeze the cell to a static value (`Copy > Paste Special > Values`) or move off Interop to the Workbook `Read Range` + `Lookup Data Table` path, which reads cached values rather than re-evaluating.
 
 ## Package