@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-server-auth-throttling-network.md

@@ -0,0 +1,95 @@
+---
+confidence: medium
+---
+
+# CV — Server errors: auth (401), unreachable (403/5xx), throttling (429), payload/word limits, network
+
+## Context
+
+All five CV activities share one transport stack and one throw site. When the CV analysis response is `null`, carries an `Error`, carries a `LocalServerError`, or has `OCRWordLimitPassed = true`, `CVSessionData.Compute` throws `System.ArgumentException` whose message is built by `cvData.ToErrorMessageWithCode()` — the `[Error code: <code>] <text>` strings below. There is **no handshake at scope entry**: CV Screen Scope (`CVScope`) only resolves the target window and publishes session data. Server reachability, auth, and throttling surface lazily on the **first child activity's first refresh** — so `scope succeeded but first CV Click fails with a server error` is normal and does NOT mean the scope is misconfigured.
+
+What this looks like — match on message text (the leading `[Error code: N]` is informational; do not pattern-match the digits alone):
+
+- `[Error code: 401] Computer Vision cannot be enabled: the current user is not authenticated.` — auth. (`ResponseInvalidApiKey`; full text continues with login / API-key paste instructions.)
+- `[Error code: 403] The specified Computer Vision server '<server>' could not be reached.` — forbidden / blocked path. (`ResponseForbiddenError`; continues with firewall/VPN guidance. `<server>` = the configured `Server` URL.)
+- `The specified Computer Vision server could not be reached.` — unreachable (`ResponseInvalidServer`, mapped from 502/503/504/408). No server name in this variant.
+- `The Computer Vision server encountered an error.` — server-side fault (`ResponseServerError`, 500).
+- `The requested data exceeds the maximum payload accepted by the server.` — payload too large (`ResponseEntityTooLarge`, 413).
+- `[Error code: 429] Computer Vision rate limit exceeded.` — throttling, optionally followed by `Please try again in <seconds> seconds.` (`CVResponseThrottling` + `PleaseRetryAfterSeconds`). Full text mentions free-tier upgrade.
+- `Error while sending request.` — network/transport. Followed by the raw `HttpRequestException` text (DNS, TLS `The SSL connection could not be established`, proxy, connection refused). (`ErrorWhileSending`.)
+- `Response from server is not valid.` — generic fall-through (`ResponseNotValid`). **This is the masking case** — see the trap note below.
+- `The ComputerVision server has hit the maximum number of words it is able to identify (<count>). Please indicate a screen with less words.` — OCR word limit, cloud (`MaxOCRCloud`). Local-server variant: `UiPath.ComputerVision.LocalServer has hit the maximum number of words it is able to identify (<count>). Please indicate a screen with less words.` (`MaxOCR`). Thrown even on HTTP 200.
+- `Server URL is empty and UseLocalServer option is false` — no server configured at runtime (`ComputerVisionServerNotSet`).
+
+What activities can produce this error:
+- **CV Screen Scope** (`CVScope`) — on its own session-refresh path (debug/healing sample lookup).
+- **CV Click** (`CvClickWithDescriptor`), **CV Type Into** (`CvTypeIntoWithDescriptor`), **CV Get Text** (`CvGetTextWithDescriptor`) — on the find/refresh that triggers a server analysis call.
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) — **faults** (throws this `ArgumentException`) on server errors. It only swallows `ElementNotFoundException` (→ `Result = false`); a server/auth/throttle error is NOT converted to `false` and still throws.
+
+What can cause it (ordered most→least common):
+- **Wrong/expired/revoked `ApiKey`, or robot not authenticated to the licensed Automation Cloud tenant** → 401. On a cloud URL the client first sends the `ApiKey` as `X-UIPATH-License`; a 401 marks the key unauthorized and silently falls back to an `X-UIPATH-Token` from the access provider (refreshing once). The 401 message surfaces only after **both** the key and the token fallback fail. On a non-cloud `Server` URL there is no token fallback.
+- **Firewall / VPN / proxy / DNS / TLS blocking the server** → 403 (`ResponseForbiddenError`), 502/503/504 (`ResponseInvalidServer`), or `Error while sending request.` / `Response from server is not valid.` (transport).
+- **Free-tier / shared-key rate limit** → 429. Retried internally (see Version/retry note) before surfacing.
+- **Screenshot too large** → 413 — very high-resolution or multi-monitor scope regions.
+- **On-prem / local CV server down or overloaded** → 500 (`ResponseServerError`) or 503.
+- **Text-dense screen** → OCR word limit (scope set on the whole desktop instead of one window, full-screen spreadsheets/terminals).
+- **`Server` URL unset at runtime** → `Server URL is empty and UseLocalServer option is false` (Project Settings server URL cleared, or `Server` arg evaluates to empty string, with `UseLocalServer = false`).
+
+> **Retry/timing note:** HTTP 429 and 520 (Cloudflare "unknown error") are retried internally every 2s within a window of `2 × TimeoutMS` (default `TimeoutMS = 30000`) before the throttled response surfaces. The job therefore **appears slow, then fails** — a single transient 429 is absorbed transparently if the server recovers in-window. `LocalServerError` responses bypass this retry loop and surface immediately.
+
+> **Pattern-matching trap — `Response from server is not valid.`:** transport exceptions (`HttpRequestException`, DNS, TLS, proxy) are caught in the client and converted to a response with `ErrorMessage` set. When no status code is attached, the message becomes `Error while sending request.` + raw text. When the body is unparseable or empty with no status, it falls through to the **generic** `Response from server is not valid.`, which **masks the real network error**. The underlying cause is visible only in the trace/runtime-dump logs, not the surfaced message. Do not conclude "server returned garbage" from this string alone — check the trace.
+
+> **Different cause, do not apply this playbook:**
+> - `Element not found` / descriptor match failed within timeout (no `[Error code]`, no server text) — the call reached the server and returned, but the descriptor did not match. Use [cv-element-not-found.md](./cv-element-not-found.md).
+> - CV Screen Scope fails to resolve the **target window** or local-server prerequisites (`Please make sure you have UiPath.ComputerVision.LocalServer package installed...`, `...requires Microsoft Visual C++ Redistributable...`, `...requires a processor that accepts AVX2...`, or `Server or OCR engine is required.` at design time) — use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - `Invalid Descriptor` (`InvalidDescriptorException`) — missing `Target`, broken image references, parse failure. Use [cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - CV Element Exists returns `false` (no exception) when you expected an error, or `ContinueOnError = true` swallowed a fault — use [cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md).
+> - `System.OperationCanceledException` / `TaskCanceledException` — job stop / parent cancellation, not a server error.
+
+## Investigation
+
+1. **Capture the exact surfaced message** and the `[Error code: N]` if present. This is the primary routing key — map it to a branch below.
+2. **Read the scope's transport properties** from the faulted activity's enclosing `CVScope`: `Server`, `ApiKey`, `UseLocalServer`, `CvMethod`, `TimeoutMS`. (For runtime-bound values, confirm what they evaluated to — `Server`/`ApiKey` may be expressions.)
+3. **Check the trace / runtime-dump logs** when the message is generic (`Response from server is not valid.`) or transport (`Error while sending request.`) — the masked HTTP status, DNS/TLS detail, or swallowed client exception is recorded there, not in the surfaced message. The runtime JSON dump is written by the dump service just before the throw.
+4. **Establish whether the failure is deterministic or volume/timing-driven.** 429 follows a burst (loops, many robots on one key) and may succeed on re-run later; 401/403/`Server URL is empty` are deterministic and fail every run regardless of load.
+5. **Confirm cloud vs on-prem `Server`.** Cloud (`cloud.uipath.com` family) has the ApiKey→token fallback; an on-prem URL sends `ApiKey` as `X-UIPATH-License` with no fallback, so a stale key fails harder there.
+
+## Resolution
+
+Match the surfaced message to a branch. Each branch names the evidence that confirms it and the evidence that rules it OUT — do not apply a fix the evidence doesn't support.
+
+### Branch A — Auth (401): `Computer Vision cannot be enabled: the current user is not authenticated.`
+Evidence: `[Error code: 401]`; fails on every run; `ApiKey` is set on the scope or in Project Settings. On a cloud URL this means **both** the `ApiKey` header and the access-token fallback were rejected.
+Ruled out when: the message is 403/5xx (reachability, not auth) or a transport string — those are not auth failures; do not rotate the key for them.
+Fix (user/config-side): verify the `ApiKey` is current — copy a fresh key from Automation Cloud > Admin > Licenses > Robots & Services into Project Settings > Computer Vision > API Key, OR ensure the robot is signed in to the licensed cloud tenant so the token fallback can authenticate. Confirm the tenant license includes CV entitlement. **Silent auth degradation:** if the workflow "used to work," a rotated/revoked key now silently falls back to the interactive token and only fails when that path also lacks entitlement — treat a sudden 401 after a key rotation as the rotated key.
+
+### Branch B — Server unreachable / forbidden (403, 502/503/504, 500)
+Evidence: `[Error code: 403] The specified Computer Vision server '<server>' could not be reached.` (forbidden / intermediary block), or `The specified Computer Vision server could not be reached.` (502/503/504/408), or `The Computer Vision server encountered an error.` (500). Deterministic for 403; intermittent for 5xx if the server is overloaded.
+Ruled out when: the message is 401 (auth) or 429 (throttle).
+Fix (user/infra-side): verify the `Server` URL is correct and reachable from the robot host. Check firewall / VPN / proxy / TLS-inspection rules allow the CV endpoint. For on-prem CV server, confirm the server process is up and not overloaded (500/503). This is an infrastructure fix, not a workflow edit.
+
+### Branch C — Throttling (429)
+Evidence: `[Error code: 429] Computer Vision rate limit exceeded.`, optionally `Please try again in <seconds> seconds.`; the job ran slow (internal 2s retries over the `2 × TimeoutMS` window) before failing; follows a burst of CV calls or many robots sharing one `ApiKey`; same workflow may pass on re-run with less load.
+Ruled out when: the failure is deterministic and load-independent — that is auth/reachability, not throttling. Do NOT "fix" a 401/403 by adding backoff.
+Fix (user-side): reduce CV call rate — fewer CV activities per loop iteration, lower concurrency/parallel robots on the shared key, add backoff/Retry around the CV step honoring the `Please try again in <seconds>` hint, stagger scheduled jobs. If on a free/community tier, upgrade the license. Raising `TimeoutMS` only widens the internal retry window (mitigation), it does not raise the rate limit.
+
+### Branch D — Payload too large (413): `The requested data exceeds the maximum payload accepted by the server.`
+Evidence: `ResponseEntityTooLarge`; scope `Target` is a very large region — full multi-monitor desktop or high-DPI capture.
+Fix (user-side): narrow the scope `Target` to a single window/region instead of the whole desktop, reducing the screenshot the client base64-encodes and POSTs.
+
+### Branch E — OCR word limit: `...has hit the maximum number of words it is able to identify (<count>)...`
+Evidence: `MaxOCRCloud` (cloud) or `MaxOCR` (`UiPath.ComputerVision.LocalServer ...`, local); thrown even on HTTP 200 because the response sets `OCRWordLimitPassed`. Scope covers a text-dense screen.
+Fix (user-side): indicate a smaller, less text-dense region — scope a single pane/window rather than a full spreadsheet, terminal, or desktop. The `<count>` in the message is the server's cap.
+
+### Branch F — Network / transport: `Error while sending request.` or generic `Response from server is not valid.`
+Evidence: `Error while sending request.` carries the raw `HttpRequestException` (DNS resolution failure, `The SSL connection could not be established`, proxy auth, connection refused). The generic `Response from server is not valid.` **masks** the same class — confirm via trace/dump (Investigation step 3) before concluding it is a malformed-response problem.
+Ruled out when: the trace shows a clean HTTP status code (then it is one of Branches A–E, not transport).
+Fix (user/infra-side): resolve robot-host networking — DNS for the CV endpoint, trusted root cert for TLS-inspection proxies, self-signed cert trust for on-prem, proxy credentials configured for the robot service.
+
+### Branch G — Server URL missing: `Server URL is empty and UseLocalServer option is false`
+Evidence: `ComputerVisionServerNotSet` at runtime; `UseLocalServer = false` and `Server` (arg or Project Settings server URL) evaluated to empty.
+Fix (user/config-side): set Project Settings > Computer Vision > Server URL, set the scope `Server` argument, or enable `UseLocalServer` if local mode is intended. If `Server` is bound to an expression, verify it doesn't evaluate to an empty string at runtime.
+
+> **Local-server `LocalServerError` note:** when `UseLocalServer = true`, the same `[Error code: N]` throw path can carry a `LocalServerError`. Engine/install failures (`Please make sure you have UiPath.ComputerVision.LocalServer package installed...`, VC++ redistributable, AVX2, `Response from local server is not valid.`) are scope-setup problems — route to [cv-scope-setup-failures.md](./cv-scope-setup-failures.md). Only the `MaxOCR` local word-limit message (Branch E) belongs here.
+
+If the surfaced message and the trace both rule out every branch above — the `ApiKey` is confirmed current and entitled, the `Server` is reachable from the robot host with no proxy/TLS/DNS interference, the load is modest with backoff in place, and the scope region and word count are within limits — the cause is outside the CV activity stack. Escalate (tenant-wide CV outage, license/entitlement change, or an upstream proxy/network event) rather than continue under this playbook. Do NOT recommend rotating keys, adding backoff, or shrinking the region when the evidence does not point to that branch.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-silent-failures-and-false-results.md

@@ -0,0 +1,124 @@
+---
+confidence: medium
+---
+
+# CV — Silent failures and false results (ContinueOnError swallow, InRegion bypass, ElementExists false-negative/positive)
+
+## Context
+
+What this looks like — **no exception is thrown**, yet a CV step behaved wrong. The job either succeeds with a wrong/empty/default output, or a later non-CV activity faults on a garbage value handed to it by a CV activity. There is no error message to match; diagnose from **output values, property settings, trace lines, and the CV dump file**.
+
+Observable symptoms:
+- **Click/Type fired at the wrong place** (or did nothing) but the activity reported success.
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) returned `True` when the element is plainly absent, or `False` when it is plainly present.
+- **CV Get Text** (`CvGetTextWithDescriptor`) returned empty (`""`), `null`, or stale/previous-screen text.
+- **OutRegion** consumed downstream is `(0,0,0,0)` (empty `Rectangle`) or a stale rectangle from a prior screen.
+- The CV server, descriptor, or window is broken, but the workflow proceeded as if nothing happened — the only sign is a `Trace.TraceError` line and a `{timestamp}_ComputerVision` dump file written before the (swallowed) throw.
+
+What activities can produce this:
+- **CV Click** (`CvClickWithDescriptor`) — `ContinueOnError`, `InRegion` arguments.
+- **CV Type Into** (`CvTypeIntoWithDescriptor`) — `ContinueOnError`, `InRegion` arguments; clipboard/focus side-paths.
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) — `Result`, `ContinueOnError`, `InRegion`, cell-targeting descriptor.
+- **CV Get Text** (`CvGetTextWithDescriptor`) — `ContinueOnError`, `InRegion`, `MethodType` (OCR vs clipboard), `RefreshBefore`.
+- **CV Screen Scope** (`CVScope`) — `ContinueOnError`, `CvMethod` (detection/OCR flags), `Server` / `UseLocalServer`.
+
+What can cause it (most→least common):
+- **`ContinueOnError = true` on a CV activity or the scope.** This is the dominant cause. The shared `Continuable*` base catches **every** exception (element-not-found, server `ArgumentException`, `InvalidDescriptorException`) when `ContinueOnError` evaluates true, traces it, and returns the activity's default output. Defaults: `CvElementExistsWithDescriptor` → `Result = false`; `CvGetTextWithDescriptor` → `Result = null`; `CvClickWithDescriptor` → still sets `OutRegion` to the default empty `Rectangle` `(0,0,0,0)`. A misconfigured server then looks identical to "element not found", and downstream logic proceeds on the default value with no signal the operation failed. `CVScope` is the one exception that still rethrows runtime-**governance** (`RuleViolationException`) faults — everything else it swallows.
+- **`InRegion` is bound, which bypasses CV entirely.** When `InRegion` is set, the find pipeline uses that rectangle directly — **no descriptor matching, no screen analysis, no validation** that anything is at those coordinates. Consequences differ by activity: `CvElementExistsWithDescriptor` **always returns `True`** (the region is non-null → it counts as "found"); `CvClickWithDescriptor` / `CvTypeIntoWithDescriptor` **fire at those raw coordinates** wherever they land. A stale or wrong `InRegion` (e.g. a prior `OutRegion` reused after the screen changed, or after a resolution/DPI change) produces wrong-coordinate clicks and false-positive existence checks with no error.
+- **`CvElementExistsWithDescriptor` converts infrastructure failures into `Result = false`** even with `ContinueOnError = false`. It catches `ElementNotFoundException` **by design** to return `false`. But a **closed/minimized target window or a failed screenshot** surfaces from session `RefreshAsync` as `ElementNotFoundException` too — so a broken target silently becomes `Result = false` (false negative), not an error. Note: other failure types (server `ArgumentException`, `InvalidDescriptorException`) still propagate from Element Exists when `ContinueOnError = false`.
+- **Cell-targeting config errors are swallowed by `CvElementExistsWithDescriptor`.** A descriptor targeting a table cell throws its informative error as an `ElementNotFoundException`, so Element Exists turns even a clear config error (e.g. `Invalid column number 0`) into `Result = false`. The message survives only in the trace and the CV dump.
+- **`CvMethod` flags disabled detection.** If the scope's `CvMethod` (or the `Section.CvScope` / `Property.CVMethod` project setting) is OCR-only or detection-only, the missing element family is served from a possibly-empty cache. Children just don't find their elements — no error from the scope. Server URL empty with no local server silently skips CV detection while OCR still runs.
+- **Clipboard / OCR side-paths in Get Text swallow errors.** Clipboard mode (`MethodType = ClipboardRow`/`ClipboardAll`): `UiService` click/select/`Ctrl+C` catch `COMException` and return `false`, which Get Text ignores — a failed copy still "succeeds" with `null`/stale clipboard text. OCR mode: `DoOcr` swallows all OCR-engine exceptions and returns no words → empty result; `RefreshBefore = false` reuses a stale OCR cache from a prior screen.
+
+What to look for:
+- **`ContinueOnError`** on the failing CV activity AND on the enclosing `CVScope` — either being `true` enables the whole silent class.
+- Whether **`InRegion`** is bound (wired from a variable / prior `OutRegion`), and whether that source could be stale.
+- Trace lines: `Trace.TraceError` of a suppressed exception (the swallowed server/descriptor error), `Could not get screenshot`, OCR-failure traces.
+- The **`{timestamp}_ComputerVision` CV dump file** — written just before a swallowed `ElementNotFoundException`; the primary forensic artifact for not-found and cell-targeting failures.
+- The actual **output value**: `Result` (`false`/`null`/unexpected `true`), `OutRegion` = `(0,0,0,0)` or a stale rectangle.
+
+> **Different cause, do not apply this playbook:**
+> - The activity **threw** `UiPath.CV.ElementNotFoundException` (`Element not found`) and faulted the job — `ContinueOnError` is `false` and `InRegion` is not bound — use [cv-element-not-found.md](./cv-element-not-found.md).
+> - The activity threw a **server error** (`[Error code: <N>] <message>`, 401/403/429/5xx, word-limit, local-server) — use [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - The activity threw `InvalidDescriptorException` (missing `Target`, broken image reference, parse failure) — use [cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - `CVScope` itself faulted at setup (window resolution, missing/uninstalled local server, missing server/OCR config) before any child ran — use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - The element **was found**, then Click/Type failed (focus, stale coordinates after find, blocked input, null `SecureString`) and threw — use [cv-action-failed-after-find.md](./cv-action-failed-after-find.md).
+> - **Get Text threw**, or returned wrong text and you have ruled out `ContinueOnError`/`InRegion`/clipboard-vs-OCR — use [cv-get-text-empty-or-wrong-result.md](./cv-get-text-empty-or-wrong-result.md).
+> - The element genuinely is below the fold and scroll-search did not reach it — use [cv-scroll-search-failures.md](./cv-scroll-search-failures.md).
+> - A table cell was targeted and you have confirmed the table/row/column config is the problem (not the swallowing) — use [cv-cell-targeting-failures.md](./cv-cell-targeting-failures.md).
+
+## Investigation
+
+1. **Identify the symptomatic output.** Determine which is wrong: a wrong-location/no-op Click or Type, an unexpected `CvElementExistsWithDescriptor` `Result`, or an empty/null/stale `CvGetTextWithDescriptor` `Result`. This selects the branch below.
+2. **Read `ContinueOnError` on the failing activity AND on the enclosing `CVScope`.** Either `true` means errors are being suppressed and returned as defaults. Check the trace for a `Trace.TraceError` line carrying the suppressed exception — that text is the real error.
+3. **Check whether `InRegion` is bound.** If set, the activity skipped all CV detection and used the rectangle verbatim. Trace the source of that rectangle (prior `OutRegion`, a variable) and whether the screen / resolution / DPI changed since it was produced.
+4. **Locate the CV dump file** `{timestamp}_ComputerVision` for the run timestamp. Its presence indicates a not-found (or swallowed cell-targeting) condition occurred even if the activity reported success/`false`.
+5. **Inspect the target window state at run time** — closed, minimized, off-screen, or a locked/unattended session can fail the screenshot and surface as `ElementNotFoundException` (→ swallowed to `Result = false` in Element Exists).
+6. **Read the scope's `CvMethod` and `Server`/`UseLocalServer`** (and any `Section.CvScope` / `Property.CVMethod` project-setting override). A detection-or-OCR-disabled method, or empty server with no local server, silently yields no elements.
+7. **For Get Text:** read `MethodType` (OCR vs clipboard) and `RefreshBefore`. Clipboard mode is fragile on non-editable targets; `RefreshBefore = false` reuses stale OCR.
+
+## Resolution
+
+Walk to the branch matching the symptom. Each names the evidence that confirms it and the evidence that rules it OUT.
+
+### Branch A — `ContinueOnError = true` is masking a real failure
+
+Evidence: `ContinueOnError` is `true` on the failing CV activity or on the enclosing `CVScope`; the trace shows a `Trace.TraceError`-logged exception (server `ArgumentException`, `InvalidDescriptorException`, or `ElementNotFoundException`) at that activity; the output is the bare default (`Result = false`/`null`, `OutRegion = (0,0,0,0)`).
+
+Ruled out when: no suppressed exception appears in the trace and no CV dump file exists for the run — then the activity genuinely succeeded and the wrong value has a different cause (try Branch B or C).
+
+Fix: the swallowed exception **is** the bug. Diagnose it under the matching sibling playbook (server → [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md), descriptor → [cv-invalid-descriptor.md](./cv-invalid-descriptor.md), not-found → [cv-element-not-found.md](./cv-element-not-found.md)). Then recommend setting `ContinueOnError = false` on that activity (or scope) so the failure surfaces instead of returning a default, unless the author deliberately wants a best-effort step — in which case recommend an explicit guard on the output (check `Result`/`OutRegion` before downstream use). Do NOT recommend leaving `ContinueOnError = true` with unguarded downstream consumption.
+
+### Branch B — `InRegion` bypassed detection (false-positive Exists, wrong-coordinate Click/Type)
+
+Evidence: `InRegion` is bound on the activity. For `CvElementExistsWithDescriptor`, `Result` is `True` regardless of screen content (and `OutRegion` equals the supplied `InRegion`). For Click/Type, the action landed at fixed coordinates unrelated to the descriptor. The supplied rectangle traces to a stale source (prior `OutRegion`, a hard-coded/old variable) or the screen/resolution/DPI changed between producer and consumer.
+
+Ruled out when: `InRegion` is unbound/empty — detection ran normally; the wrong result is then Branch A or a genuine match/scroll/cell issue (route to the sibling playbooks).
+
+Fix: stop relying on `InRegion` for validated targeting. Either clear `InRegion` so the activity matches the descriptor against the live screen, or recompute the region immediately before use from a fresh find. For an existence check, an `InRegion`-bound `CvElementExistsWithDescriptor` is meaningless — it cannot return `False`; replace it with a descriptor-based check. Confirm the producing activity ran on the same screen state and DPI as the consumer.
+
+### Branch C — Element Exists false negative: closed/minimized window or failed screenshot
+
+Evidence: `CvElementExistsWithDescriptor` returned `False`, but the element is present when checked manually; a `{timestamp}_ComputerVision` dump exists; the target window was closed, minimized, off-screen, or the session was locked at run time; trace may show `Could not get screenshot`. `ContinueOnError = false` and `InRegion` unbound (otherwise Branch A/B).
+
+Ruled out when: the target window was confirmed visible and foreground at run time and a screenshot succeeded — then `False` is a genuine descriptor mismatch, route to [cv-element-not-found.md](./cv-element-not-found.md).
+
+Fix: ensure the target window is open, restored, and able to come to the foreground before the check (an unattended/locked session blocks the screenshot). The scope re-resolves its root window by cached selector until `TimeoutMS`; if the window legitimately may be absent, treat `False` as "could not verify" rather than "definitely absent" and add an explicit window-state guard upstream.
+
+### Branch D — Cell-targeting config error swallowed into `Result = false`
+
+Evidence: the descriptor targets a **table cell**; `CvElementExistsWithDescriptor` returned `False`; the CV dump / trace contains an informative cell message such as `Invalid column number <N>`, `Table only contains <N> columns and column number is <M>`, `Invalid row number <N>`, `Could not find table. Cell targeting supports only tables as target`, or `Table does not have any column with column name containing <name>`. These never reach the workflow level because Element Exists swallows them.
+
+Ruled out when: the descriptor does not target a cell, or no cell message appears in the trace/dump — then it is a plain match failure (Branch C / not-found).
+
+Fix: this is a configuration error, not an absent element. Correct the cell descriptor per the captured message (column/row index must be ≥ 1 and within range; column-name/row-contains text must match the extracted table text). Diagnose the cell config under [cv-cell-targeting-failures.md](./cv-cell-targeting-failures.md). Recommend switching off the swallowing path (validate the cell config with a throwing CV activity, or set `ContinueOnError = false` and read the surfaced message) so the informative error is no longer lost.
+
+### Branch E — Get Text returns null / empty / stale silently
+
+Evidence: `CvGetTextWithDescriptor` `Result` is `null` (→ check Branch A; `ContinueOnError = true` yields `null`), `""`, or text from a previous screen. Clipboard mode (`MethodType = ClipboardRow`/`ClipboardAll`) on a non-editable target, focus stolen between click and `Ctrl+C`, or another process holding the clipboard → empty/stale; the click/copy `COMException` is swallowed. OCR mode with `RefreshBefore = false` reuses a stale OCR cache; a swallowed OCR-engine failure yields zero words → `""`.
+
+Ruled out when: `ContinueOnError = false`, `MethodType` matches the target type (clipboard only for editable/selectable text), and `RefreshBefore = true` — then route detailed wrong-text diagnosis to [cv-get-text-empty-or-wrong-result.md](./cv-get-text-empty-or-wrong-result.md).
+
+Fix: pick the right mode — use OCR mode for non-editable on-screen text; use clipboard mode only for selectable/editable inputs. Set `RefreshBefore = true` when the screen changed since the prior CV activity. If `ContinueOnError = true`, see Branch A.
+
+### Branch F — `CvMethod` disabled the needed detection family
+
+Evidence: multiple children in the scope silently find nothing (or only text, or only controls); the scope's `CvMethod` (or `Section.CvScope` / `Property.CVMethod` project setting) is OCR-only or detection-only, or `Server` is empty with no local server. No error from the scope.
+
+Ruled out when: `CvMethod` includes both element detection and OCR and a server (cloud or local) is configured — then missing elements are a genuine match failure or server issue, not a disabled method.
+
+Fix: set `CvMethod` to include the families the descriptors need (control detection for control descriptors, OCR for text descriptors), and ensure a `Server` URL or `UseLocalServer` is configured so detection can run. This is a scope-setting change — see also [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+
+## Post-presentation actions
+
+This resolution path is **interactive** whenever the fix edits the user's workflow — changing `ContinueOnError`, clearing or rebinding `InRegion`, changing `MethodType` / `RefreshBefore`, correcting a cell descriptor, or changing the scope's `CvMethod`. The orchestrator MUST call `AskUserQuestion` before any edit, and follow these rules:
+
+1. **Sharing a file path is not approval.** A path the user gave for reading the project does not authorize editing it. Issue a separate `AskUserQuestion` before any edit.
+2. **Never bundle "gather input" with "apply fix" in one option.** Split into two steps: gather the input, then surface the specific diff and confirm separately.
+3. **Surface the concrete diff before asking** — file path, activity `IdRef` or line, current value, proposed value (e.g. `ContinueOnError: True → False`, `InRegion: <bound> → <unbound>`, `CvMethod: OcrOnly → ControlsAndOcr`).
+4. **One question per file/fix; list every file touched** (e.g. XAML plus any mirrored Object Repository file). Do not silently propagate a substitution to side-channel files.
+5. **If interactive approval is unavailable or errors, do not edit.** Present the diff as a recommendation and stop. A recommendation-only close is acceptable; a silent edit is never acceptable.
+
+## Stop / escalate
+
+If `ContinueOnError` is `false` on the activity and scope, `InRegion` is unbound, the target window was visible and foreground (screenshot succeeded), `CvMethod` includes the needed families with a reachable server, Get Text uses the correct mode with `RefreshBefore = true`, and no swallowed exception or cell message appears in the trace or the `{timestamp}_ComputerVision` dump — then the wrong result is NOT a silent-suppression artifact. Stop applying this playbook and route by what actually happened: a genuine match failure ([cv-element-not-found.md](./cv-element-not-found.md)), a server error ([cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md)), or a post-find action failure ([cv-action-failed-after-find.md](./cv-action-failed-after-find.md)). Do not recommend toggling `ContinueOnError` or `InRegion` when the evidence does not show suppression — that is a fabricated fix.

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

@@ -0,0 +1,8 @@
+# Computer Vision (CV) Activities Presentation Rules
+
+- **Activities** — use the display name in prose (e.g., "CV Click", "CV Type Into", "CV Get Text", "CV Element Exists", "CV Screen Scope"), not the fully qualified class name. Include the class name in parentheses on first mention so an agent can match a stack trace (e.g., "CV Click (`CvClickWithDescriptor`)"). Don't lead with the class name.
+- **Descriptor target** — refer to the target by its friendly / label text or what the user would see on screen (e.g., "the 'Submit' button", "the 'Total' cell in the invoice table"), not by the raw descriptor JSON or serialized payload. Describe anchors the same way (e.g., "anchored to the 'Amount' label").
+- **Do not show raw descriptor payloads** — never paste the serialized `CvDescriptor` / descriptor JSON as the primary identifier. Show the descriptor's expression text or `IdRef` only when the diagnostic requires it (e.g., the invalid-descriptor case where the `Descriptor value: '<expression>'` itself is what failed).
+- **CV server** — refer to the server by its URL (the configured `Server` value, e.g., `<serverUrl>`) or as "the local server" when `UseLocalServer = true`, not by internal config IDs. State whether it is cloud or local when it matters for the diagnostic.
+- **Scope** — refer to the container as "the CV Screen Scope", and name its relevant config in plain language (e.g., "the scope's OCR engine", "the scope's server URL"), not by raw property paths unless surfacing a concrete fix diff.
+- **Properties / enum values** — name properties and enum values as the activity surfaces them (`TimeoutMS`, `ContinueOnError`, `InRegion`, `RefreshBefore`, `MethodType = OCR`), and state in plain language what a recommended change does (e.g., "set `RefreshBefore = true` so it re-reads the current screen before extracting text").

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

@@ -0,0 +1,15 @@
+# Computer Vision (CV) Activity Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules, cross-cutting error-class routing, and testing prerequisites for Computer Vision Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Invalid Descriptor | High | `UiPath.CV.InvalidDescriptorException`, thrown synchronously when the activity resolves the `Descriptor` argument — **before any find attempt**. Composite message: `Invalid Descriptor` + optional `Reason: Target must be set` (null `Target`) or `Reason: Invalid image reference or value` (image refs unresolvable across a copied descriptor) + `Descriptor value: '<expression>'`. No `Reason:` line = the expression failed to evaluate/parse (cause traced, not attached). `CvElementExistsWithDescriptor` **FAULTS** here (does not return `false`). Hits programmatically built / copied / hand-edited descriptors. Distinct from `ElementNotFoundException`, which throws after a find ran. | [cv-invalid-descriptor.md](./playbooks/cv-invalid-descriptor.md) |
+| Cell-Targeting Failures | High | `UiPath.CV.ElementNotFoundException` carrying one of nine cell-specific sentences (`Could not find table. Cell targeting supports only tables as target`, `Table only contains <count> columns and column number is <n>`, `Invalid column number <n>`, `Table does not have any column with column name containing <name>`, `Invalid row number <n>`, `No row in column <c> had a text containing <v>`, etc.) on `Cv*WithDescriptor` whose `Descriptor.Target.CellExtraInfo` is set. Table not detected, index out of range or `< 1` (1-based), column-name/row-value mismatch, scrolled-row drift. Trap: `Version < V3` disables cell targeting and surfaces the **generic `Element not found`** instead. `CvElementExistsWithDescriptor` swallows the sentence to `Result = false`. Distinct from plain not-found (generic message, non-cell target). | [cv-cell-targeting-failures.md](./playbooks/cv-cell-targeting-failures.md) |
+| Element Not Found | Medium | `UiPath.CV.ElementNotFoundException` / `Element not found` after the retry loop exhausts `TimeoutMS` (timeout has NO separate exception type). Three root causes share the message — genuine UI-changed mismatch, scope-refresh failure (`Could not get screenshot` traced, blank dump screenshot), OCR degradation (text on screen but dump's detected text empty). `CvElementExistsWithDescriptor` returns `Result = false`. The `*_ComputerVision` dump screenshot is the primary discriminator. Distinct from scroll-exhausted (`Scrolled...`), cell sentences, and `InvalidDescriptorException`. | [cv-element-not-found.md](./playbooks/cv-element-not-found.md) |
+| Scroll-Search Failures | Medium | `Scrolled the entire screen, but element was not found` (`ElementNotFoundException`, hardcoded English, not localized) on a find activity with `ScrollDirection != None`. Wrong scroll axis, scroll point (scope center + `CVScope.ScrollOffset`) off the scrollable pane, `NumberOfScrolls` too high (element skipped between frames), `DelayScreenshotAfterScroll` too short, silent scroll-skip when scope root is not a CV driver element, or genuine absence. Side effect: reset types `Ctrl+Home`/`Ctrl+End` into the app. `CvElementExistsWithDescriptor` swallows it to `false`. The word `Scrolled` is the discriminator from plain [cv-element-not-found.md](./playbooks/cv-element-not-found.md). | [cv-scroll-search-failures.md](./playbooks/cv-scroll-search-failures.md) |
+| Server: Auth / Throttling / Network | Medium | `System.ArgumentException` built by `CVSessionData.Compute` / `ToErrorMessageWithCode()`, `[Error code: <N>]` text: `401` auth (`...current user is not authenticated.`), `403`/502/503/504/500 unreachable (`The specified Computer Vision server '<server>' could not be reached.`), `429` throttling (`Computer Vision rate limit exceeded.`, retried 2s over `2xTimeoutMS` -> slow-then-fail), `413` payload, cloud OCR word limit (`...maximum number of words...`), transport (`Error while sending request.`, masking `Response from server is not valid.`), `Server URL is empty and UseLocalServer option is false`. Surfaces lazily on a child's first refresh, NOT at scope entry. `CvElementExistsWithDescriptor` **faults** (only swallows not-found). Match text, not HTTP digits. Local-server install errors -> scope-setup. | [cv-server-auth-throttling-network.md](./playbooks/cv-server-auth-throttling-network.md) |
+| Scope Setup Failures | Medium | Fault at `CVScope` entry **before any child activity ran** (scope rethrows the inner fault unwrapped). `Please make sure you have UiPath.ComputerVision.LocalServer package installed...` (`System.ArgumentException`, `UseLocalServer=true`, package absent on the run machine), `Server or OCR engine is required.` (design-time, run blocked), `The target Element was not specified for this activity.` (`ElementNotSetException`, root selector `COMException` on a matched window, or `Target` genuinely null), AVX2 / `Microsoft Visual C++ Redistributable 2015-2022` local-server prerequisites, design-time placement (`Activity is valid only inside a CV Screen Scope`, nested scope, `Descriptor or InputRegion is required`), raw `NullReferenceException` (child outside scope at runtime). Distinct from server errors during a child's analysis call. | [cv-scope-setup-failures.md](./playbooks/cv-scope-setup-failures.md) |
+| Action Failed After Find | Medium | Find **succeeded**, the click/keystroke failed or hit the wrong place. CV acts on screenshot-derived **coordinates** (hardware events forced). Signatures: raw driver/`COMException` with NO `UiPath.CV.*` type and no CV resource key (`UninitializedNodeException`->`ElementNotSetException` / `The target Element was not specified for this activity.`); `Value cannot be null. (Parameter 'Secure')` (`ArgumentNullException`, CV Type Into null `SecureString`); an unwrapped non-CV type (e.g. `InvalidOperationException`) rethrown from the find task; or **no error** with `OutRegion = (0,0,0,0)` / empty-stale clipboard `Result`. Window moved between analysis and action, focus stolen, input blocked (locked/RDP/UAC), or non-editable clipboard target. No `*_ComputerVision` dump (that is written only when the find throws). | [cv-action-failed-after-find.md](./playbooks/cv-action-failed-after-find.md) |
+| Get Text Empty / Stale / Wrong | Medium | `CvGetTextWithDescriptor` **completed without faulting** but `Result` is empty / `null` / stale / partial / wrong (no exception to match). OCR mode: silent OCR scrape failure (swallowed -> empty), stale cache (`RefreshBefore = false`), region-edge clipping (only words overlapping `OutRegion` composed), language/accents mismatch. Clipboard mode (`MethodType = ClipboardRow`/`ClipboardAll`): non-editable target, focus theft, or another process holding the clipboard -> empty/stale silently (100ms read timeout swallowed). `Scroll = true` + OCR stitch hang (NOT bounded by `TimeoutMS`). `MethodType` splits the branches. Distinct from a thrown `ElementNotFoundException` / server error. | [cv-get-text-empty-or-wrong-result.md](./playbooks/cv-get-text-empty-or-wrong-result.md) |
+| Silent Failures & False Results | Medium | **No exception**, wrong/empty/default output — diagnose from outputs, properties, trace, and the `*_ComputerVision` dump. `ContinueOnError = true` on the activity or `CVScope` catches every exception (`ElementNotFoundException`, server `ArgumentException`, `InvalidDescriptorException`) -> default output (`Result = false`/`null`, `OutRegion = (0,0,0,0)`); `Trace.TraceError` holds the real error. `InRegion` bound bypasses CV entirely -> `CvElementExistsWithDescriptor` **always `True`**, Click/Type fire at raw coordinates. `CvElementExistsWithDescriptor` converts closed/minimized-window / failed-screenshot to `Result = false` (false negative) and swallows cell-config errors. `CvMethod` disabling a detection family. Distinct from any case where the activity actually threw. | [cv-silent-failures-and-false-results.md](./playbooks/cv-silent-failures-and-false-results.md) |

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

@@ -0,0 +1,42 @@
+# Database Activities Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity's class matches the reported failure (`UiPath.Database.Activities.ExecuteQuery`, `ExecuteNonQuery`, `ExecuteCommand`, `DatabaseConnect`, `DatabaseTransaction`, `BulkUpdate`). `Execute Query` (SELECT → `DataTable`) and `Execute Non Query` (modification → `AffectedRecords`) share a connection model but differ in output type — treat a wrong-activity report as its own branch.
+- **Database / connection** — the `ProviderName` and the server/database in the `ConnectionString` match the database the user is asking about. A connection string pointing at a different server, database, or provider is unrelated data.
+- **SQL statement** — the `Sql` in evidence is the statement the user reports running. Do not substitute a similar query from another activity in the same workflow.
+- **Project compatibility** — whether the project is **Windows** or **Windows - Legacy**, and whether the failure began right after a migration. Load-bearing for provider/driver-mismatch findings.
+- **Robot / machine identity** — the Robot host where the job ran matches the one the user reports. Installed database drivers (ODBC/managed providers) are per-host; evidence from a different host is not transferable.
+- **Package version** — the `UiPath.Database.Activities` version on the Robot matches the one the user reports. Provider-path behaviour and exception text shift across major versions.
+- **Timestamp** — the failure occurred during the window the user reported. Load-bearing for timeout and CLR-crash investigations (transient blocking / memory pressure may not reproduce on demand).
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+### Execute Query / Execute Non Query / Run Command
+
+1. **Workflow source** — read the data-activity node from the `.xaml` to capture: how the connection is supplied (`ExistingDbConnection` variable vs inline `ConnectionString` + `ProviderName`), the literal `Sql` or bound expression, `CommandType`, `Parameters`, and `TimeoutMS`. For `ExistingDbConnection`, trace the variable back to the `Connect to Database` / `Start Transaction` that produces it and confirm scope and ordering.
+2. **Inner provider exception** — from `uip or jobs get <job-key> --output json` → `Info`. UiPath wraps the provider error as `A database error occurred` / `Execute Query: <message>`; read the **inner** exception — it carries the real syntax error, provider code (`ORA-…`, SQL Server error number), or `Keyword not supported` text.
+3. **Project compatibility + package version** — `project.json` (`targetFramework` / `Windows` vs `Windows-Legacy`) and the pinned `UiPath.Database.Activities` version. Required for provider-mismatch and CLR-crash branches.
+4. **Property placement** — confirm the `SELECT` text is in the `Sql` property and the connection string is in `ConnectionString` (not crossed), and that the connection string's quotes are balanced.
+5. **Result-set size / provider** — the expected row count the query materializes into a `DataTable`, and whether the engine is Oracle returning a `REF CURSOR`. Required for the `0xE0434352` CLR-crash branch.
+
+### Connect to Database / Start Transaction
+
+1. **Connection configuration** — the literal `ConnectionString` and `ProviderName` on the activity, and whether the matching driver is installed on the Robot host.
+2. **Output variable wiring and scope** — the `DatabaseConnection` output variable name, the scope it is declared in, and every downstream data activity that reads it. A connection declared inside a nested `Sequence` is out of scope (and `Nothing`) for activities outside it.
+3. **Transaction commit/rollback outcome (Start Transaction only)** — correlate the **job final state** with the **actual database effect** and the in-scope activity logs: a `Success` job with no committed data, or with no child-activity log lines at all, points to a transaction-specific fault (swallowed rollback or a body-skip package bug) rather than a child-statement error. Capture the `UiPath.Database.Activities` version (v1.5.0 is the known body-skip build) and confirm whether each child activity binds the scope's output connection to its `ExistingDbConnection` (a child on its own inline connection runs outside the transaction). See [start-transaction-failures.md](./playbooks/start-transaction-failures.md).
+
+## Testing Prerequisites
+
+When testing hypotheses for Database Activities issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — the exact faulted class and its display name; whether the statement verb matches the activity (SELECT→Execute Query, modification→Execute Non Query).
+2. **Connection provenance** — inline connection vs `ExistingDbConnection`; if the latter, the producing `Connect`/`Start Transaction`, its output variable, scope, and execution order relative to the faulted activity.
+3. **Inner provider message** — the unwrapped provider exception text and code, not just the UiPath `A database error occurred` wrapper.
+4. **`Sql` and `Parameters`** — the resolved statement (log it if built from an expression) and whether values are parameterized (`@name` via `Parameters`) or concatenated into the string.
+5. **`ProviderName` + driver availability** — the configured provider and whether its driver is installed on every Robot host that runs the process.
+6. **Project compatibility** — Windows vs Windows-Legacy, and whether the failure coincided with a migration.
+7. **`TimeoutMS` + DB-side duration** — the configured timeout (milliseconds) and the query's real runtime measured independently against the database.
+8. **Package version** — the `UiPath.Database.Activities` version (provider-path and CLR-crash branches are version-sensitive).

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

@@ -0,0 +1,41 @@
+# Database Activities
+
+Activities from the `UiPath.Database.Activities` package for querying and modifying relational databases over ADO.NET. Every data activity runs against a `DatabaseConnection` opened by a `Connect to Database` or `Start Transaction` activity, or against an inline `ConnectionString` + `ProviderName` configured on the activity itself. The underlying provider (SQL Server, Oracle, MySQL, ODBC, OLE DB, …) is selected by `ProviderName` and determines connection-string syntax and error text.
+
+## How Database Activities Connect
+
+The package separates **connection** from **execution**:
+
+1. **Open** — `Connect to Database` (`DatabaseConnect`) or `Start Transaction` (`DatabaseTransaction`) takes a `ConnectionString` + `ProviderName` and produces a `DatabaseConnection` object as output.
+2. **Execute** — `Execute Query`, `Execute Non Query`, `Run Command`, and the bulk/insert activities consume that connection via their `ExistingDbConnection` input (or carry their own inline `ConnectionString` + `ProviderName` and open a throwaway connection per call).
+3. **Close** — `Disconnect`, the end of the `Connect to Database` scope, or the `Start Transaction` commit/rollback releases the connection.
+
+A data activity therefore fails for one of two broad reasons: the **connection** it was handed is missing/invalid/expired (open step), or the **statement** it ran is wrong (execute step). Knowing which step produced the error narrows the investigation.
+
+## Key Activities
+
+- **Connect to Database** (`DatabaseConnect`) — open a connection. Properties: `ConnectionString`, `ProviderName`, output `DatabaseConnection`. The connection variable's scope determines where downstream activities can use it. Connection-open failures (especially the Excel-as-a-database / ACE OLE DB case) are catalogued in the [Connect to Database failures playbook](./playbooks/connect-to-database-failures.md).
+- **Start Transaction** (`DatabaseTransaction`) — open a connection inside a transactional scope; child activities run under one transaction, committed at scope end (or rolled back on fault). Properties: `ConnectionString`, `ProviderName`, `UseTransaction`, output `DatabaseConnection`.
+- **Disconnect** (`DatabaseDisconnect`) — close a `DatabaseConnection`.
+- **Execute Query** (`ExecuteQuery`) — run a `SELECT` and return a `DataTable`. Properties: `ExistingDbConnection` (or inline `ConnectionString`/`ProviderName`), `Sql`, `CommandType`, `Parameters`, `TimeoutMS` (milliseconds; default `30000`), output `DataTable`. See the [Execute Query failures playbook](./playbooks/execute-query-failures.md).
+- **Execute Non Query** (`ExecuteNonQuery`) — run `INSERT`/`UPDATE`/`DELETE`/DDL and return the affected-row count. Properties as above, output `AffectedRecords` (`Int32`). Failures (output-parameter sizing, unsafe SQL/parameters, empty `Sql`, driver load) are catalogued in the [Execute Non Query failures playbook](./playbooks/execute-non-query-failures.md).
+- **Run Command** (`ExecuteCommand`) — run a statement or stored procedure where the result shape is configured via `CommandType` (`Text` vs `StoredProcedure`). Properties: `ExistingDbConnection`/inline connection, `Sql` (command/proc name), `CommandType`, `Parameters`, `TimeoutMS`.
+- **Insert / Bulk Update Database** (`BulkUpdate`) — write a `DataTable` to a target table. Properties: `ExistingDbConnection`/inline connection, `TableName`, the source `DataTable`, `TimeoutMS`.
+
+## Common Failure Patterns
+
+`Execute Query` is the most failure-prone surface; its seven branches are catalogued in the [Execute Query failures playbook](./playbooks/execute-query-failures.md). The same connection- and provider-level patterns apply to `Execute Non Query`, `Run Command`, and the bulk activities:
+
+- **Null / expired / out-of-scope connection** — the `DatabaseConnection` handed to a data activity is `Nothing`: the `Connect to Database` / `Start Transaction` did not run first, its output variable was never wired into `ExistingDbConnection`, the connection variable is scoped to an inner `Sequence`, or the connection was already disposed. Surfaces as `Object reference not set to an instance of an object`.
+- **Driver / provider mismatch after migration** — after upgrading a project from **Windows - Legacy** (.NET Framework) to **Windows** (.NET 6+), the configured `ProviderName` or connection-string keywords are rejected by the modern provider (`Keyword not supported`), or the required driver is not installed on the Robot host. SQL Server commonly needs `System.Data.SqlClient` → `Microsoft.Data.SqlClient`; MySQL/other engines need their managed or ODBC driver installed.
+- **SQL syntax / unsafe concatenation** — malformed `Sql`, or SQL built by string concatenation (`"... WHERE id = " + var`), which breaks parsing and is a SQL-injection risk. Surfaces as `Execute Query: A database error occurred` wrapping the provider's syntax error. Fix: parameterize with named `@parameters` via the `Parameters` collection.
+- **Query text in the connection-string field** — the SQL statement was pasted into `ConnectionString` instead of `Sql`, or quotes in the connection string are unbalanced; the parser then chokes, often surfacing as a misleading "database does not exist".
+- **Command timeout exceeded** — the statement ran longer than `TimeoutMS` (milliseconds; default `30000` = 30 s). Surfaces as `Timeout expired`. Distinguish a legitimately long query (raise `TimeoutMS`) from a runaway/un-indexed query (fix the index/query).
+- **CLR-level crash (`0xE0434352`)** — a managed-runtime fault bypassing the activity exception path: an oversized result set exhausting Robot memory, an incompatible native provider path (notably Oracle `REF CURSOR`), or a stale `UiPath.Database.Activities` build. `0xE0434352` is the generic .NET unhandled-exception code — the DB context narrows it.
+- **Wrong activity for the statement type** — `Execute Query` for a `SELECT` (→ `DataTable`); `Execute Non Query` for modifications (→ `AffectedRecords`). Crossing them returns empty/meaningless output or fails the output type binding.
+
+## Package
+
+NuGet: `UiPath.Database.Activities`
+
+Activities target ADO.NET; the active provider is chosen per activity/connection via `ProviderName`. Project compatibility (**Windows** vs **Windows - Legacy**) changes the default provider and is a frequent migration-time failure cause. Version-specific bugs are documented in the relevant playbooks.

package/skills/uipath-troubleshoot/references/activity-packages/database-activities/playbooks/connect-to-database-failures.md

@@ -0,0 +1,104 @@
+---
+confidence: medium
+---
+
+# Connect to Database Failures (Excel / Access via OLE DB / ODBC)
+
+## Context
+
+A `UiPath.Database.Activities` `Connect to Database` (`DatabaseConnect`) activity opens an ADO.NET connection from a `ConnectionString` + `ProviderName` and outputs a `DatabaseConnection` for downstream `Execute Query` / `Execute Non Query` / `Run Command` activities. Connection-open failures cluster heavily around **file-based providers** — using an Excel workbook (or Access database) as the data source through the ACE OLE DB or an ODBC driver — where the connection string, driver registration, process bitness, and file locking all have to line up.
+
+Rule out the package confusion first: **`Connect to Database` lives in `UiPath.Database.Activities`, not `UiPath.Excel.Activities`.** Reading an Excel file through database activities is the deliberate "Excel-as-a-database" pattern (SQL over a workbook), distinct from the Excel package's `Read Range` / `Use Excel File`. If the user went looking for `Connect to Database` in the Excel package, clearing up that mismatch is step zero.
+
+What this looks like — Connect to Database faults surface as one of these signatures:
+
+- `System.ArgumentException` / `Format of the initialization string does not conform to specification starting at index N` / a generic "Invalid connection string" — branch 1.
+- `System.InvalidOperationException: The 'Microsoft.ACE.OLEDB.12.0' provider is not registered on the local machine` (or `Microsoft.Jet.OLEDB.4.0` for legacy `.xls`) — branch 2.
+- `The process cannot access the file '<path>' because it is being used by another process` / a sharing violation from the engine — branch 3.
+- `The type initializer for 'Microsoft.Data.SqlClient.SqlConnection' threw an exception` (or another provider type-initializer / driver-init failure) on a project moved to **Windows** (.NET) — branch 4.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Malformed / wrong connection string** — the `ConnectionString` does not match the provider's required layout. The correct ACE OLE DB shape for a modern `.xlsx` is:
+
+   ```text
+   Provider=Microsoft.ACE.OLEDB.12.0;Data Source=C:\Path\To\File.xlsx;Extended Properties="Excel 12.0 Xml;HDR=YES;"
+   ```
+
+   `HDR=YES` treats the first row as column headers; use `HDR=NO` when the sheet has no header row. Common mistakes: unquoted or missing `Extended Properties`, missing `Data Source`, using the `Excel 12.0 Xml` variant against a legacy `.xls` (which needs `Excel 8.0` and the `Microsoft.Jet.OLEDB.4.0` provider), or SQL text accidentally pasted into the connection string (that variant routes to [execute-query-failures.md](./execute-query-failures.md) branch 4).
+2. **Provider not registered / architecture (bitness) mismatch** — the ACE OLE DB / ODBC driver named in the connection string is not installed, or its bitness does not match the process. A **Windows** project runs as a **64-bit** process and needs the **64-bit** Microsoft Access Database Engine (ACE); a 32-bit-only ACE install (commonly bundled with 32-bit Office) produces "provider is not registered on the local machine". Mixed Office bitness on the host complicates the install (the 64-bit engine may refuse to install alongside 32-bit Office without the `/quiet` workaround).
+3. **File lock / sharing violation** — the workbook is open in Excel or held by another process (an orphaned process from a prior run, a concurrent job, a OneDrive/sync or AV client), so the engine cannot acquire the file. File-based providers request a write lock by default, so even a read-only SELECT fails while the file is held.
+4. **Provider init failure after migration / wrong `ProviderName`** — on a project switched from **Windows - Legacy** to **Windows** (.NET), leaving `ProviderName` empty (or defaulted to a SqlClient value) makes the activity initialize the SQL Server provider, which throws a type-initializer exception in the .NET runtime — even though the intended target is Excel. The provider must be set explicitly: `System.Data.OleDb` for ACE OLE DB, or `System.Data.Odbc` for an ODBC DSN/driver.
+
+What to look for:
+
+- **The exception class and message** — first signal, maps directly to a branch per the signature list. "provider is not registered" → branch 2; "initialization string" / `ArgumentException` → branch 1; "used by another process" → branch 3; "type initializer for 'Microsoft.Data.SqlClient...'" → branch 4.
+- **`ConnectionString` + `ProviderName`** (literal values) from the workflow source — the provider name, the `Data Source` path and its extension (`.xlsx` vs `.xls`), and the `Extended Properties` block.
+- **Project compatibility and process bitness** — `project.json` (`Windows` vs `Windows-Legacy`); a **Windows** project is a 64-bit process. Load-bearing for branches 2 and 4.
+- **Driver inventory on the Robot host** — whether the Microsoft Access Database Engine (ACE) or the ODBC driver is installed, and its **bitness**, on the machine that ran the job (not the dev machine).
+- **Workbook lock state at run time** — whether the file was open in Excel, held by an orphaned process, or on a sync-backed path.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error and configuration.** From `uip or jobs get <job-key> --output json` → `Info`: the exception class and full message (including inner exception). From workflow source (`.xaml`): the `Connect to Database` node's literal `ConnectionString` and `ProviderName`, and the `Data Source` path/extension inside the connection string. From `project.json`: the project compatibility (`Windows` vs `Windows-Legacy`).
+
+2. **Branch the diagnostic on the signature.**
+   - `ArgumentException` / "initialization string" / "Invalid connection string" → branch 1; go to step 3.
+   - "provider is not registered on the local machine" → branch 2; go to step 4.
+   - "used by another process" / sharing violation → branch 3; go to step 5.
+   - "type initializer for 'Microsoft.Data.SqlClient...'" / driver-init on a Windows project → branch 4; go to step 6.
+
+3. **Confirm branch 1 (connection string).** Compare the literal `ConnectionString` against the provider's required layout. For Excel/ACE: `Provider=`, `Data Source=<full path>`, and a quoted `Extended Properties="Excel 12.0 Xml;HDR=YES;"`. Check the file extension matches the variant (`.xlsx` → `Excel 12.0 Xml` + ACE 12.0; `.xls` → `Excel 8.0` + Jet 4.0). Confirm no SQL text leaked into the connection string and that all quotes are balanced.
+
+4. **Confirm branch 2 (provider not registered / bitness).** Determine the process bitness from project compatibility (**Windows** = 64-bit). Check whether the ACE/ODBC driver is installed on the Robot host and its bitness (Control Panel → Programs, or the registry under `HKLM\SOFTWARE\...\Microsoft.ACE.OLEDB.12.0` vs the `WOW6432Node` 32-bit hive). "Not registered" with a 64-bit process and only a 32-bit ACE present confirms the mismatch.
+
+5. **Confirm branch 3 (file lock).** Check whether the workbook was open in Excel or held by another process at the failure time: an orphaned process holding the handle, a concurrent job touching the same file, or a sync/AV client. The message names the file path — confirm it is the workbook the connection targets.
+
+6. **Confirm branch 4 (provider init / wrong ProviderName).** Confirm the project is **Windows** (.NET) and read `ProviderName` on the activity. Empty or a SqlClient value while the `ConnectionString` is clearly an Excel/ACE OLE DB string confirms the branch — the runtime is initializing SqlClient instead of OLE DB.
+
+The root cause must name **which of the four surfaces** the failure maps to, with the specific evidence: the exception text, the literal `ConnectionString`/`ProviderName`, the project compatibility/bitness, and the host's driver inventory. A generic "could not connect" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Connection string:**
+  - Use the provider-correct layout. Excel `.xlsx` via ACE OLE DB: `Provider=Microsoft.ACE.OLEDB.12.0;Data Source=<full path>.xlsx;Extended Properties="Excel 12.0 Xml;HDR=YES;"` (`HDR=NO` if the sheet has no header row). Legacy `.xls`: `Provider=Microsoft.Jet.OLEDB.4.0;...;Extended Properties="Excel 8.0;HDR=YES;"`.
+  - Quote the `Extended Properties` value, supply a full `Data Source` path, and keep SQL out of the connection string (the `SELECT` belongs in the `Execute Query` `Sql` property).
+
+- **Branch 2 — Provider not registered / bitness mismatch:**
+  - Match the **process** bitness, not Office's. A **Windows** project is 64-bit → install the **64-bit** Microsoft Access Database Engine (ACE) on every Robot host.
+  - If 32-bit Office is installed and blocks the 64-bit engine installer, run the engine installer with the `/quiet` switch to force the install alongside it.
+  - Alternative: set the project to **Windows - Legacy** (32-bit) only if a 64-bit engine genuinely cannot be installed — but prefer installing the 64-bit ACE so the modern runtime is used.
+
+- **Branch 3 — File lock:**
+  - Ensure the workbook is closed (and no orphaned process holds it) before the robot runs; kill stray processes as a hygiene step at job start if a prior run can leak a handle.
+  - For read-only workloads (SELECT only), open the connection read-only so the engine does not request a write lock — for ACE OLE DB add `Mode=Read` to the connection string. (Some setups instead carry a read flag in `Extended Properties`; verify against your provider version.)
+
+- **Branch 4 — Provider init / wrong ProviderName:**
+  - Set `ProviderName` explicitly on the activity. For Excel/Access via ACE OLE DB: `System.Data.OleDb`. For an ODBC DSN/driver: `System.Data.Odbc`. Do **not** leave it empty or set to a SqlClient value when the target is a file-based source.
+  - This is the canonical fix when a working Windows-Legacy project starts failing with a `Microsoft.Data.SqlClient` type-initializer error after migration to **Windows** — the empty provider was implicitly resolving to SqlClient.
+
+### Querying the workbook (after a successful connect)
+
+Once connected, address each sheet as a table by appending `$` to the sheet name and wrapping it in brackets: `SELECT * FROM [Sheet1$]`. A named range is addressed as `[RangeName]`. Query-side failures (syntax, parameters, timeouts) are covered in [execute-query-failures.md](./execute-query-failures.md).
+
+## Anti-patterns (what NOT to do)
+
+- **"Install the 32-bit Access Database Engine to match 32-bit Office."** The driver bitness must match the **process** bitness, not the installed Office bitness. A **Windows** project is a 64-bit process and needs the 64-bit ACE even when Office is 32-bit. Matching Office instead reproduces branch 2.
+- **"Leave `ProviderName` empty and let it auto-detect."** On a **Windows** (.NET) project an empty provider resolves toward SqlClient and throws a type-initializer error against an Excel source (branch 4). Always set the provider explicitly for file-based sources.
+- **"Wrap Connect in a Try Catch that catches `System.Exception` and continues."** A bare catch that logs and swallows turns a failed connection into a downstream null-connection fault (`Object reference not set` in the next `Execute Query` — see [execute-query-failures.md](./execute-query-failures.md) branch 1), which is harder to diagnose than the original connect error. Use Try-Catch only with a real recovery path (retry a transient lock, mark the queue item Failed, notify, or re-throw a domain-specific exception) — and catch the specific provider/`DataException`, not bare `System.Exception`, so unrelated faults still surface.
+
+## Prevention (cross-branch)
+
+- Confirm the activity is `Connect to Database` from `UiPath.Database.Activities` (the Excel package has no such activity), and that "Excel-as-a-database" is the intended pattern rather than `Read Range` / `Use Excel File`.
+- Provision every Robot host with the **64-bit** Microsoft Access Database Engine when the project is **Windows**, and verify the driver bitness as part of host setup — not at first failure.
+- Set `ProviderName` explicitly (`System.Data.OleDb` / `System.Data.Odbc`) on file-based connections and pin it in the workflow rather than relying on defaults.
+- Keep the target workbook closed during runs and address sheets as `[Sheet$]`; for read-only flows open the connection read-only (`Mode=Read`) to avoid lock contention.
+
+## Related
+
+- [execute-query-failures.md](./execute-query-failures.md) — the query-side surface (null-connection from a failed connect, SQL syntax, query-in-connection-string, timeouts).
+- [`../overview.md`](../overview.md) — the package connection model (Connect → `DatabaseConnection` → data activities).