@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-get-text-empty-or-wrong-result.md

@@ -0,0 +1,117 @@
+---
+confidence: medium
+---
+
+# CV Get Text returns empty, stale, or wrong text (OCR mode and clipboard mode)
+
+## Context
+
+The activity **completed successfully** (no fault, `Result` is set) but the extracted text is empty, partial, outdated, or wrong. Symptom-driven: "the result is empty / null / old text but the activity did not throw." This is the defining signature — **CV Get Text** swallows the failures that produce it, so there is no exception to match on for most branches.
+
+What activities can produce this:
+- **CV Get Text** (`CvGetTextWithDescriptor`, namespace `UiPath.CV.Activities`) — the only activity here. Extracts text from a CV-detected element via OCR (`MethodType = OCR`) or via click + select + copy + clipboard read (`MethodType = ClipboardRow` / `ClipboardAll`).
+
+What this looks like:
+- `Result` is `""` / `null` / `Nothing` while every other activity in the run succeeded.
+- `Result` holds text from a **previous** screen state (stale), not the screen as it is now.
+- `Result` is partial — a few words missing, or words half-clipped at the edge of the read region.
+- No error message in the logs for any of the above (silent). The two exception branches below are the exceptions.
+
+What can cause it (ordered most → least common):
+- **OCR scrape failed silently.** `MethodType = OCR`. The OCR engine threw; the failure is caught, traced, and swallowed, producing **zero** OCR words for the region. The activity then composes text from an empty word set → `Result = ""`. No fault is raised.
+- **Stale OCR cache (`RefreshBefore = false`).** `MethodType = OCR`. With `RefreshBefore` unchecked, the activity reuses the OCR analysis cached from a **previous** screen state instead of re-scraping. If the screen changed since that analysis, the returned text is outdated. (When `RefreshBefore = true`, the activity issues a fresh OCR refresh of the session before reading.)
+- **Region overlap clipping.** `MethodType = OCR`. Text is composed only from OCR words whose region **overlaps** the matched rectangle. Words sitting half-outside the matched area are dropped → partial result.
+- **OCR language / accents mismatch.** `MethodType = OCR`. Engine recognised the glyphs as different characters (accents, non-Latin script, wrong configured language) → wrong text, not empty.
+- **Clipboard read returned nothing (silent).** `MethodType = ClipboardRow` / `ClipboardAll`. The select-and-copy sequence relies on the target being **keyboard-selectable editable text**. The click/select/copy keystrokes and the clipboard read all swallow their failures — clicks return `false` and that value is ignored; the clipboard read has a **100ms** timeout and any exception (including timeout, or another process holding/overwriting the clipboard) is caught and returns `null`. Result: empty/wrong text with no error.
+
+What to look for:
+- `MethodType` of the activity — it cleanly splits the OCR branches from the clipboard branches. Read it from the XAML / activity properties before choosing a branch.
+- `RefreshBefore` value (OCR branches only).
+- The CV Screen Scope's `OCREngine` configuration (OCR branches only).
+- Whether the target is genuinely selectable editable text (clipboard branches only) — a label, image caption, or read-only canvas is **not**.
+
+> **Different cause, do not apply this playbook:**
+> - The activity **threw** `ElementNotFoundException` and the descriptor never matched within `TimeoutMS` — the element was not found at all, not a text-extraction problem. Use [cv-element-not-found.md](./cv-element-not-found.md).
+> - The activity **threw** with a server/OCR error message built by `ToErrorMessageWithCode()` (carries an HTTP/error code, mentions auth, an unreachable server, a 429, or an OCR word limit) — the CV/OCR server call itself failed and surfaced. Use [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - The CV Screen Scope itself faulted on setup, or no `OCREngine` is configured and the design-time error `Server or OCR engine is required.` appears — Use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - The activity **threw** `Scrolled the entire screen, but element was not found` (`Scroll = true` + OCR, area never matched) — that is a scroll-search exhaustion, not an extraction-of-found-content problem. Use [cv-scroll-search-failures.md](./cv-scroll-search-failures.md).
+> - The result is correct text but a downstream **CV Click / CV Type Into** then acted on the wrong place — Use [cv-action-failed-after-find.md](./cv-action-failed-after-find.md).
+> - The target is a table cell and the row/column was misidentified — Use [cv-cell-targeting-failures.md](./cv-cell-targeting-failures.md).
+
+## Investigation
+
+1. **Confirm the no-fault signature.** Verify the activity did **not** throw — `Result` is set but empty/stale/partial/wrong, and the run continued. If an exception was thrown, route to the sibling playbook matching its message/type (see the block above) — do not proceed here. The two exception branches below (Branch E, Branch F) are the only in-playbook faults.
+2. **Read `MethodType`** from the faulted activity's properties in XAML. `OCR` → Branches A–D. `ClipboardRow` / `ClipboardAll` → Branch E and Branch G.
+3. **For OCR**, read `RefreshBefore` and the parent CV Screen Scope's `OCREngine`. Capture the screen state at the time of the run (screenshot / video / logged region if available) and compare against the expected text.
+4. **For clipboard**, identify what the target actually is: selectable editable text vs a label / image / read-only region. Check whether another process or the robot itself touches the clipboard around the same time.
+5. **For partial OCR results**, compare the matched `OutRegion` rectangle against the position of the missing words — words outside the rectangle are expected to be dropped.
+
+## Resolution
+
+Choose the first branch whose evidence holds. Do not apply a fix the evidence does not support — e.g. do not change `OCREngine` when the result is a clipboard-mode empty (no OCR runs in clipboard mode).
+
+### Branch A — OCR scrape failed silently (empty result, `MethodType = OCR`)
+
+Evidence: `MethodType = OCR`, `Result` is empty, the screen visibly contains text in the matched region, and there is **no** server error message in the logs (a real server error would route to [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md)). The OCR engine exception is swallowed, so absence of a message does not mean OCR succeeded.
+
+Fix: verify the CV Screen Scope's `OCREngine` is configured and reachable (endpoint/key for a server engine, or the local engine's dependencies present). Re-run with OCR engine tracing if available to surface the swallowed exception. If the engine is healthy but still returns nothing, the screen may be too dense (word limit) — that surfaces as a server error, route accordingly.
+
+### Branch B — Stale text from a cached OCR analysis (`RefreshBefore = false`)
+
+Evidence: `MethodType = OCR`, `RefreshBefore = false` (or unchecked), `Result` matches the screen as it was **before** the most recent screen change rather than the current state. Common after a navigation/click earlier in the workflow changed the screen without a scope refresh.
+
+Fix: set `RefreshBefore = true` on the activity so it re-scrapes OCR against the current screen before reading. This is the single most common stale-text cause.
+
+### Branch C — Partial result, words clipped at the region edge (`MethodType = OCR`)
+
+Evidence: `MethodType = OCR`, `Result` contains most but not all expected text, and the missing words sit at or beyond the boundary of the matched `OutRegion` rectangle. Only OCR words overlapping the matched area are composed into the result.
+
+Fix: broaden the matched area so the full text falls inside it — adjust the descriptor / `InRegion` to cover the whole text block, or target a container element rather than a tight sub-element. Do not raise `TimeoutMS` — timeout is not the issue.
+
+### Branch D — Wrong characters / accents (`MethodType = OCR`)
+
+Evidence: `MethodType = OCR`, `Result` is non-empty but characters are wrong — accents stripped or mangled, non-Latin script garbled.
+
+Fix: configure the OCR engine in the CV Screen Scope for the correct language/character set. This is an OCR-engine configuration change, not a CV Get Text property change.
+
+### Branch E — Clipboard mode returned empty/wrong, no fault (`MethodType = ClipboardRow` / `ClipboardAll`)
+
+Evidence: `MethodType = ClipboardRow` or `ClipboardAll`, `Result` is empty/wrong, **no** exception thrown. The click, the select keystrokes, and the clipboard read each swallow their own failures (clicks return `false`, ignored; clipboard read times out at 100ms and returns `null` on any exception).
+
+Fix — decision by what the target is:
+- **Target is not selectable editable text** (a label, image caption, static/read-only field, canvas): clipboard mode cannot work — the select-all/copy sequence (`End` / `Shift+Home`, or `Ctrl+End` / `Ctrl+Shift+Home`) only selects in keyboard-editable text. Switch `MethodType` to `OCR`. This is the most common clipboard-mode failure.
+- **Another process touches the clipboard** (a clipboard manager, a concurrent robot, the operator) around the same time: isolate the run so nothing else writes the clipboard during the activity.
+- **The read raced the 100ms clipboard timeout** on a slow machine: the read window is fixed; retry the activity, or switch to `OCR` mode which does not depend on the clipboard.
+
+### Branch F — Clipboard mode: `ElementNotFoundException` thrown (`MethodType = ClipboardRow` / `ClipboardAll`)
+
+Evidence: `MethodType = ClipboardRow` or `ClipboardAll`, the activity **threw** `ElementNotFoundException`, and the descriptor *did* match (the area was found — distinguish from [cv-element-not-found.md](./cv-element-not-found.md) where the descriptor never matched). This fires when the activity could not create a UI element from the matched area before clicking it. In practice this element is cloned from the scope's root, so this is a defensive guard that is near-dead unless the scope root element is null.
+
+Fix: this points to a degraded CV Screen Scope root element, not to the text target. Verify the scope resolved its target window/element correctly. Use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md) if the scope's target resolution is the actual problem.
+
+### Branch G — Scrollable content extraction failure (`Scroll = true` + `MethodType = OCR`)
+
+Evidence: `Scroll = true` **and** `MethodType = OCR`. The area was found, but the scroll-capture-and-stitch phase that gathers OCR across the scrollable content returned wrong/empty text or hung. Two distinct facts matter here:
+- **`TimeoutMS` does NOT bound this phase.** The scroll-extraction phase receives the raw workflow cancellation token, not the `TimeoutMS`-bound token. If the activity appears to hang here, raising or lowering `TimeoutMS` has no effect — do not recommend it. Only job-level cancellation stops it.
+- The extraction service is resolved when the activity is constructed; a missing service registration faults at activity instantiation (before execution), not as an empty result.
+
+Fix:
+- **Hang / no progress:** the content is likely not actually scrollable, or the scroll point lands off-target. Tune `ScrollOffset` (on the CV Screen Scope) so the scroll lands on the right pane, and `DelayScreenshotAfterScroll` so each captured frame is settled. Do not adjust `TimeoutMS` — it does not apply.
+- **Empty/partial stitched text:** server/OCR errors during the per-scroll analysis degrade the stitch; verify the OCR engine health as in Branch A.
+- **Note:** `Scroll = true` combined with a **clipboard** `MethodType` is invalid and is flagged at design time — it is not a runtime branch here.
+
+## Post-presentation actions
+
+Branches B, C, E (the switch-to-OCR fix), and G edit user workflow files (the `RefreshBefore` / `MethodType` / `Scroll`-related properties of the CV Get Text activity, or `ScrollOffset` / `DelayScreenshotAfterScroll` / `OCREngine` on the CV Screen Scope). This resolution path is **interactive**. Before any edit, the orchestrator MUST call `AskUserQuestion`.
+
+Rules the agent MUST follow:
+
+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 input, then surface the diff and confirm.
+3. **Surface the diff before asking.** The question must name the file path, the activity `IdRef` or line, the current value, and the proposed value (e.g. `RefreshBefore: false → true`, or `MethodType: ClipboardRow → OCR`).
+4. **One question per fix, listing every file touched.** If a fix changes both the CV Get Text activity and its parent CV Screen Scope, list both.
+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 `MethodType = OCR` with `RefreshBefore = true`, the `OCREngine` is confirmed configured/reachable and healthy, the matched region covers the full expected text, and the result is still empty/wrong — the OCR engine is failing for this content; escalate to the OCR engine owner with the captured screen and region rather than continue under this playbook. If `MethodType` is a clipboard mode, the target is confirmed selectable editable text, and nothing else touches the clipboard, yet the result is still empty — switch to `OCR` mode per Branch E and escalate the clipboard path separately. Do not recommend changing `OCREngine` for a clipboard-mode failure or raising `TimeoutMS` for a `Scroll = true` extraction — the evidence rules both out.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-invalid-descriptor.md

@@ -0,0 +1,102 @@
+---
+confidence: high
+---
+
+# CV — Invalid Descriptor (missing Target, broken image references, parse/evaluation failure)
+
+## Context
+
+What this looks like — `UiPath.CV.InvalidDescriptorException`, a multi-line composite message assembled from up to three parts (in order):
+
+- `Invalid Descriptor` — always present, first line.
+- `Reason: Target must be set` — second line, ONLY when the descriptor's `Target` is null.
+- `Reason: Invalid image reference or value` — second line, ONLY when the descriptor uses image targets/anchors that can't be resolved at runtime.
+- `Descriptor value: '<expression>'` — always last line. `<expression>` is the **expression text** of the `Descriptor` argument (the variable name or literal), NOT the serialized descriptor payload. Empty (`Descriptor value: ''`) when the expression text can't be extracted.
+
+When there is no `Reason:` line — just `Invalid Descriptor` followed directly by `Descriptor value: '<expression>'` — the descriptor expression itself failed to evaluate or parse (generic wrap). The original parse/evaluation exception is traced but replaced; it is NOT attached as an inner exception, so the trace is the only place to recover the underlying cause.
+
+The job faults **synchronously the moment the activity resolves the `Descriptor` argument** — thrown in `GetDescriptor` during `GetRuntimeContext`, **before any find attempt**. This is what cleanly separates it from element-not-found: the activity never ran a search.
+
+What activities can produce this error:
+- **CV Click** (`CvClickWithDescriptor`) — `Descriptor` argument.
+- **CV Type Into** (`CvTypeIntoWithDescriptor`) — `Descriptor` argument.
+- **CV Get Text** (`CvGetTextWithDescriptor`) — `Descriptor` argument.
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) — `Descriptor` argument. **This activity FAULTS — it does NOT return `Result = false`.** `GetRuntimeContext` (which resolves the descriptor) runs before the `try` block that swallows `ElementNotFoundException`, so `InvalidDescriptorException` escapes uncaught. A `false` result means the element wasn't found, not a bad descriptor — different cause (see below).
+
+What can cause it:
+- **Descriptor's `Target` is null.** The runtime `Descriptor` argument evaluated to a `CvDescriptor` with no `Target`. Produces the `Reason: Target must be set` line. Almost always a **programmatically built `CvDescriptor`** missing its `Target` node, a variable passed to `Descriptor` that wasn't fully populated, or a hand-edited/corrupted descriptor string in XAML.
+- **Image references can't be resolved.** The descriptor uses image-based targets/anchors (`IsImageUsed`) but the image payloads can't be copied from the activity's hidden `DesignTimeDescriptor` (`TrySetImages` failed). Produces the `Reason: Invalid image reference or value` line. Happens when a **descriptor variable is copied/passed between activities** and references images by id that exist only in the *originating* activity's design-time data, or a hand-edited descriptor carries image ids with no embedded payload.
+- **Descriptor expression fails to evaluate/parse.** Any exception while evaluating the `Descriptor` InArgument — null variable, bad VB/C# expression, malformed/truncated serialized descriptor string, deserialization error. Produces **no `Reason:` line** (just `Invalid Descriptor` + `Descriptor value:`).
+
+Rare in Studio-authored workflows — the CV recorder/designer always sets `Target` and embeds design-time images. Hit mainly by **programmatically built descriptors, descriptor variables copied between activities, or hand-edited XAML**.
+
+What to look for:
+- The `Reason:` line (present/absent and which text) is the primary branch key — read it first.
+- The faulted activity is a `Cv*WithDescriptor` whose `Descriptor` argument is bound to a **variable or expression**, not a recorder-captured inline descriptor.
+
+> **Different cause, do not apply this playbook:**
+> - Descriptor was captured by the recorder and the element simply wasn't on screen within the timeout → `ElementNotFoundException` / descriptor match failed *after* a find attempt. Use [cv-element-not-found.md](./cv-element-not-found.md).
+> - `CvElementExistsWithDescriptor` returns `Result = false` (no fault) → element not found, descriptor was valid. Use [cv-element-not-found.md](./cv-element-not-found.md) or [cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md) for false-negative/positive traps.
+> - The CV Screen Scope (`CVScope`) failed to set up (target window, server URL, API key, OCR config) — fault originates in the scope, before any descriptor activity ran. Use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - `System.ArgumentException` from CV server analysis (auth 401, unreachable 403/5xx, throttling 429, word limits) → server-side, not descriptor. Use [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - Element was found but the click/type then failed → [cv-action-failed-after-find.md](./cv-action-failed-after-find.md).
+
+## Investigation
+
+The error is unambiguous about the *class* of failure; the `Reason:` line selects the branch. No find ever ran, so logs/screenshots of "what was on screen" are irrelevant here.
+
+1. Read the full message. Note whether a `Reason:` line is present and its exact text (`Target must be set` vs `Invalid image reference or value`), and capture the `Descriptor value: '<expression>'` text — it names the offending argument expression.
+2. Locate the faulted activity in XAML by the exception's activity `IdRef`. Confirm it is a `Cv*WithDescriptor` and read its `Descriptor` argument binding.
+3. Determine how `Descriptor` is set: an inline recorder-captured descriptor, a variable assigned earlier, or an expression. Recorder-captured inline descriptors with no further mutation rarely produce this error — a variable/expression binding is the usual culprit.
+4. If `Reason: Target must be set` — trace where the bound variable/descriptor was constructed and confirm its `Target` is populated.
+5. If `Reason: Invalid image reference or value` — confirm the descriptor uses image targets/anchors and was sourced from a **different** activity than the one running it (copied variable, cross-workflow reuse). The running activity's own `DesignTimeDescriptor` is the only image source it can copy from.
+6. If **no `Reason:` line** — the descriptor expression threw. Pull the underlying cause from the **trace** (it is traced but not attached as an inner exception). Inspect the `Descriptor value: '<expression>'` expression for null variables, malformed serialized strings, or bad VB/C# syntax.
+
+## Resolution
+
+Branch on the `Reason:` line. Each branch maps to a distinct fix; the evidence that selects it is the message text plus the descriptor's origin.
+
+### Branch A — `Reason: Target must be set`
+
+Evidence: message second line is `Reason: Target must be set`. The runtime `CvDescriptor` has a null `Target`.
+
+Fix: ensure the `Descriptor` argument resolves to a descriptor with a populated `Target`.
+- **If the descriptor is built programmatically:** set its `Target` before passing it in. Do not pass a partially-constructed descriptor.
+- **If a recorder-captured descriptor would be simpler:** re-capture the target in the designer (CV recorder always sets `Target`) and bind the activity to that, instead of the hand-built variable.
+- **If the XAML descriptor string was hand-edited/corrupted:** re-capture via the recorder rather than patching the string.
+
+> Ruled out: if `Target` is populated in the source descriptor and the activity still throws `Target must be set`, the variable being passed at runtime is not the one inspected — trace the actual binding before recommending a `Target` change.
+
+### Branch B — `Reason: Invalid image reference or value`
+
+Evidence: message second line is `Reason: Invalid image reference or value`. The descriptor uses image targets/anchors but the runtime image payloads couldn't be copied from the running activity's `DesignTimeDescriptor`.
+
+Fix: the image-based descriptor must be **owned by the activity that uses it** — image payloads live in each activity's hidden `DesignTimeDescriptor`, captured at design time, and cannot be borrowed from another activity.
+- **If a descriptor variable was copied/reused from another activity or workflow:** re-capture the image target directly on the failing activity in the designer so its own `DesignTimeDescriptor` holds the image bytes. Do not pass an image-based descriptor variable across activities.
+- **If the descriptor was serialized/deserialized (lost image payloads):** stop round-tripping image-based descriptors through serialization; bind the activity to a freshly captured descriptor.
+
+> Ruled out: text/non-image descriptors never hit this branch (the image-copy path only runs when `IsImageUsed` is true). If the descriptor has no image target/anchor, this is not your message — re-read the `Reason:` line.
+
+### Branch C — No `Reason:` line (expression parse/evaluation failure)
+
+Evidence: message is `Invalid Descriptor` followed directly by `Descriptor value: '<expression>'`, with NO `Reason:` line. The `Descriptor` expression itself threw while evaluating.
+
+Fix: correct the expression named in `Descriptor value: '<expression>'`.
+- **Null variable:** the variable bound to `Descriptor` was never assigned (or assigned null). Ensure it is populated before the activity runs.
+- **Malformed/truncated serialized descriptor string:** a hand-edited or programmatically assembled descriptor string failed to deserialize. Re-capture via the recorder or fix the serialization.
+- **Bad VB/C# expression:** syntax/type error in the `Descriptor` expression. Fix the expression.
+- The underlying exception is in the **trace** (traced, not attached) — read it to identify which of the above applies before recommending a fix.
+
+## Post-presentation actions
+
+Every fix above edits user source files (the `Descriptor` argument binding, the descriptor-building code, or re-capture in XAML). The resolution is **interactive** — the orchestrator MUST obtain explicit approval before any edit.
+
+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 concrete diff and confirm separately.
+3. **Surface the diff before asking.** The apply-fix question MUST include the file path, the activity `IdRef`, the `Descriptor` argument's current value, and the proposed value.
+4. **One question per file/fix.** If multiple files are touched (e.g. XAML plus the code that builds the descriptor), list every file or ask file-by-file.
+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.
+
+## Stop / escalate
+
+If the `Reason:` line and the descriptor's origin are confirmed and the fix above is applied, the error is resolved at the activity. If `Target` is verifiably populated, the descriptor is non-image yet throws the image-reason, or the expression is valid and assigned — the runtime binding being evaluated is not the one inspected: stop and re-trace the actual `Descriptor` value at the faulted activity rather than continuing under this playbook.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-scope-setup-failures.md

@@ -0,0 +1,136 @@
+---
+confidence: medium
+---
+
+# CV — Screen Scope setup failures (window resolution, local server prerequisites, missing server/OCR config)
+
+## Context
+
+The **CV Screen Scope** (`CVScope`) is the container every CV activity runs inside. Its `ExecuteAsync` resolves the target window, builds a CV session (`CVSessionData`), and only then runs the body. A fault during that setup faults the scope **before any child activity executes** — and the scope's `OnFault` rethrows the inner fault **unwrapped**, so the exception you see may have originated in the scope, not in the child.
+
+**Core diagnostic split — do this first:**
+- **Fault BEFORE any child activity ran** (no `CV Click` / `CV Type Into` / `CV Element Exists` / `CV Get Text` trace line; the faulted activity in XAML is the `CV Screen Scope` itself) → scope-setup problem. **This playbook.**
+- **Fault INSIDE a child** (a child activity has a start trace, the descriptor match was attempted) → find/server/action problem. Route to [cv-element-not-found.md](./cv-element-not-found.md), [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md), or [cv-action-failed-after-find.md](./cv-action-failed-after-find.md). Not this playbook.
+
+What this looks like — any of these patterns, all faulting at scope entry:
+
+- `Please make sure you have UiPath.ComputerVision.LocalServer package installed in order to use local server mode.` — `UseLocalServer=true` but the LocalServer package is absent. Fires at both design time (validation, blocks run) and runtime (`System.ArgumentException`).
+- `Server or OCR engine is required.` — design-time validation only: no `Server`, `UseLocalServer` not true, no `OCREngine`, no project-settings `Server`. Blocks the run; never a runtime throw.
+- `The target Element was not specified for this activity.` — scope `Target` was set, but reading the root element's selector raised a `COMException` at session creation; the COM failure is remapped to this message (`ElementNotSetException`). Also the literal message when `Target` is genuinely null.
+- `UiPath.ComputerVision.LocalServer requires a processor that accepts AVX2 instructions.` — local server runtime error: CPU lacks AVX2.
+- `UiPath.ComputerVision.LocalServer requires Microsoft Visual C++ Redistributable 2015-2022 for X64.` — local server runtime error: MSVC redistributable missing.
+- `Activity is valid only inside a CV Screen Scope` — design-time validation: a child CV activity is outside any scope.
+- `Activity can not be in another Screen Scope container` — design-time validation: a `CV Screen Scope` is nested inside another `CV Screen Scope`.
+- `Descriptor or InputRegion is required` — design-time validation: a child CV activity has neither a `Descriptor` nor an `InputRegion`.
+- A **raw `System.NullReferenceException` with no message** — a child CV activity executed **outside** a `CV Screen Scope` at runtime (validation bypassed). See Branch F.
+
+What activities can produce this:
+- **CV Screen Scope** (`CVScope`) — the scope itself, for window-resolution / local-server / missing-config faults.
+- **All child CV activities** — **CV Click** (`CvClickWithDescriptor`), **CV Type Into** (`CvTypeIntoWithDescriptor`), **CV Element Exists** (`CvElementExistsWithDescriptor`), **CV Get Text** (`CvGetTextWithDescriptor`) — when the enclosing scope faults before their body runs, OR for the design-time validation constraints (`Activity is valid only inside a CV Screen Scope`, `Descriptor or InputRegion is required`) that attach to the child.
+
+What can cause it (ordered most→least common):
+- **LocalServer package missing on the robot machine.** `UseLocalServer=true` (set directly or via project settings) but `UiPath.ComputerVision.LocalServer` is not installed. The runtime check (`VerifyEdgeServerInstalled`) cannot load `UiPath.CVLocalServer.ServiceConfig`. Most common on first deploy to a new machine: the workflow ran fine where the package was present.
+- **Scope window selector no longer resolves.** `Target` selector doesn't match (app not open, title/version/language drift, no visible window). Standard UiAutomation target-resolution errors surface from the scope.
+- **Root element selector unreadable (COMException).** The target window matched, but died/changed between attach and session creation, so reading its selector throws `COMException` → remapped to `The target Element was not specified for this activity.`
+- **Missing server/OCR configuration (design time).** Neither a cloud `Server`+`ApiKey`, nor `UseLocalServer`, nor an `OCREngine` is configured → `Server or OCR engine is required.`
+- **Local server runtime prerequisites.** CPU without AVX2, or MSVC 2015-2022 x64 redistributable missing → the LocalServer cannot start.
+- **Design-time constraint violations.** Child outside scope, nested scope, no descriptor/region.
+- **Child executed outside a scope at runtime (rare).** Validation bypassed via dynamic/composed workflow → raw `NullReferenceException`.
+
+> **Different cause, do not apply this playbook:**
+> - A child activity **started** and the descriptor match timed out → [cv-element-not-found.md](./cv-element-not-found.md).
+> - Server reachable but returns 401/403/429/5xx, payload/word errors **during a child's analysis call** (not at scope entry) → [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - `... has hit the maximum number of words it is able to identify (<count>). Please indicate a screen with less words.` — the OCR word cap. It surfaces **lazily on the first child's analysis call**, not at scope entry, so it is an analysis-time fault → [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - The descriptor itself is malformed (missing `Target`, broken image refs, parse failure) → [cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - `The target Element was not specified for this activity.` remapped from `UninitializedNodeException` **after the find succeeded** (a child started and matched, then the action ran) → [cv-action-failed-after-find.md](./cv-action-failed-after-find.md). This playbook's variant is the **scope-entry** one: the message fires before any child ran.
+> - Click/type failed **after** the element was found (focus, stale coords, blocked input) → [cv-action-failed-after-find.md](./cv-action-failed-after-find.md).
+> - Activity returned a wrong/empty result without faulting → [cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md).
+
+## Investigation
+
+1. **Confirm the fault is at scope entry, not in a child.** Read the trace/log order: is there any `CV Click` / `CV Type Into` / `CV Element Exists` / `CV Get Text` start line before the fault? If a child started, this is not a scope-setup failure — route per the negative-match block. If the faulted activity in XAML is the `CV Screen Scope` itself and no child ran, continue.
+2. **Identify the message pattern** against the Context list. The message text is the primary router — match on it, not on the exception type alone (the scope rethrows children's exceptions unwrapped, and several distinct causes share `System.ArgumentException`).
+3. **Determine design-time vs runtime.** Validation messages (`Server or OCR engine is required.`, `Activity is valid only inside a CV Screen Scope`, `Activity can not be in another Screen Scope container`, `Descriptor or InputRegion is required`, and the design-time form of the LocalServer message) **block the run** as `InvalidWorkflowException` / `ValidationError` — the job never started. A faulted *running* job points to the runtime branches instead.
+4. **Read scope properties from XAML** when relevant: `UseLocalServer`, `Server`, `ApiKey`, `OCREngine`, `CvMethod`, `Target` (selector + `WaitForReady`), `ContinueOnError`. Also check **project settings** — `UseLocalServer` and `Server` can be set there and override an empty scope-level value.
+5. **For LocalServer messages, confirm the package on the failing machine** — not the dev machine. The package presence is machine/project-local.
+6. **For window-resolution faults**, confirm the target app is open and its window visible at the moment the scope runs (same checks as a UIA application scope: title/version/language drift, minimized-to-tray, second monitor on unattended).
+
+## Resolution
+
+Walk the decision tree. Match the **message text** first, then the corroborating evidence. Choose the first branch whose evidence holds.
+
+### Branch A — LocalServer package missing (runtime)
+
+**Evidence.** Running job faulted with `System.ArgumentException`: `Please make sure you have UiPath.ComputerVision.LocalServer package installed in order to use local server mode.` `UseLocalServer=true` (scope or project settings). No child ran.
+
+**Fix.** Add the `UiPath.ComputerVision.LocalServer` NuGet package to the project so the robot machine has it (project dependency change, not a workflow XAML edit) — **OR**, if local-server mode was not intended, set `UseLocalServer=false` on the scope (or in project settings) and configure a cloud `Server`+`ApiKey` instead (XAML/properties edit → see Post-presentation actions).
+
+**Ruled out** if the project already references `UiPath.ComputerVision.LocalServer` and the dependency restored on this machine — then the failure is a local server *runtime* error (Branch E), not a missing package.
+
+### Branch B — Server or OCR engine missing (design time)
+
+**Evidence.** `Server or OCR engine is required.` The run was **blocked at validation** — the job never started. No `Server`, `UseLocalServer` not true, no `OCREngine`, and no `Server` in project settings.
+
+**Fix.** Configure exactly one analysis source on the scope: set `Server`+`ApiKey` (cloud), or set `UseLocalServer=true` with the LocalServer package installed, or attach an `OCREngine` (XAML/properties edit → Post-presentation actions). This is design-time only; it never appears on a running job.
+
+### Branch C — Scope window selector did not resolve
+
+**Evidence.** Scope-entry fault with target-resolution / UIA selector errors (e.g. selector-not-found, scope timeout) — `Target` was set but the window was not located. No COM failure on a matched window. The app is closed, or the selector drifted (title/version/language), or the window is not visible.
+
+**Fix.** Same remediation family as a UIA application scope: confirm the app is open with a visible window when the scope runs; relax the scope `Target` selector (wildcard volatile parts, prefer stable attributes); ensure an earlier step launches/activates the app; raise `WaitForReady` / scope timeout for cold-start races (XAML/properties edit → Post-presentation actions).
+
+**Distinct from Branch D:** here no window matched. In D a window matched but its selector became unreadable.
+
+### Branch D — Root element selector unreadable at session creation (COMException)
+
+**Evidence.** `The target Element was not specified for this activity.` on a scope where `Target` **is** set (not null). The window matched, then died/changed between attach and `CVSessionData` construction, so reading the root selector threw `COMException`. Often intermittent; clusters with apps that close/repaint fast.
+
+**Fix.** Stabilize the window before the scope: precede with an app-state/Element-Exists wait so the scope only runs against a live, settled window; add retry around the scope; raise `DelayBefore` if the window repaints immediately after appearing (XAML/properties edit → Post-presentation actions).
+
+**Ruled out** when `Target` is actually empty/null in XAML — then the same message is the literal "target not set" case, fixed by setting `Target` (still Post-presentation).
+
+### Branch E — Local server runtime error (service unavailable / AVX2 / VC++)
+
+**Evidence.** `UseLocalServer=true`, package **present**, but a runtime `System.ArgumentException` carrying a `LocalServerError`:
+- `UiPath.ComputerVision.LocalServer requires a processor that accepts AVX2 instructions.` → CPU lacks AVX2 (older/virtualized hardware).
+- `UiPath.ComputerVision.LocalServer requires Microsoft Visual C++ Redistributable 2015-2022 for X64.` → MSVC redistributable missing.
+- Service-unavailable / engine-load text → the local server process failed to start.
+
+**Fix (environment, not workflow):**
+- **AVX2.** Move the robot to AVX2-capable hardware, or switch the scope to cloud mode (`UseLocalServer=false` + `Server`+`ApiKey`). AVX2 is not installable.
+- **VC++.** Install the Microsoft Visual C++ Redistributable 2015-2022 (x64) on the robot machine.
+- **Service failed to start.** Confirm the LocalServer install is intact; reinstall the package; check for a broker/dependency load failure in the robot logs.
+
+LocalServer-error responses bypass the throttling retry loop, so they surface immediately (no slow-then-fail). Do **not** treat AVX2/VC++ as transient — they will not self-heal on retry.
+
+### Branch F — Child executed outside a CV Screen Scope at runtime
+
+**Evidence.** A **raw `System.NullReferenceException` with no message** from a child CV activity, where the workflow was composed/invoked dynamically (e.g. `Invoke Workflow` into a fragment, dynamically loaded XAML) so the design-time `InCVScope` constraint was bypassed. Normally impossible in Studio-authored workflows — the constraint blocks publish.
+
+**Fix.** Ensure the child CV activity runs inside a real `CV Screen Scope` ancestor. If the workflow dynamically composes activities, wrap them so the scope is present at runtime (XAML/structure edit → Post-presentation actions). Do **not** chase the `NullReferenceException` as a CV server or descriptor bug — the null is the missing `CVSessionData` data-context, nothing more.
+
+### Design-time constraint violations (Branches in validation, run blocked)
+
+These never appear on a running job; they block publish/run as validation errors. Fix in the designer, then re-run:
+- `Activity is valid only inside a CV Screen Scope` — move the child CV activity inside a `CV Screen Scope`.
+- `Activity can not be in another Screen Scope container` — un-nest the inner `CV Screen Scope`; a scope cannot contain another scope.
+- `Descriptor or InputRegion is required` — set the child's `Descriptor`, or supply an `InputRegion`.
+- The design-time form of the LocalServer message → Branch A's package fix.
+
+## Post-presentation actions
+
+Branches A (when flipping `UseLocalServer` / setting cloud `Server`+`ApiKey`), B, C, D, F, and the design-time constraint fixes **edit user source files** (scope XAML properties, child placement, project settings). That resolution path is **interactive**.
+
+Rules the agent MUST follow:
+
+1. **Sharing a file path is not approval.** A path the user gave for reading the project does not authorize editing. Issue a separate `AskUserQuestion` before any edit.
+2. **Surface the diff before asking.** The apply-fix question must name the file path, the activity `IdRef` (or property/line), the current value, and the proposed value — e.g. `CVScope.UseLocalServer: true → false` plus the `Server`/`ApiKey` to add.
+3. **Never bundle "gather input" with "apply fix" in one option.** Splitting required: gather input, then surface the concrete diff and confirm separately.
+4. **One question per file/fix.** List every file touched (scope XAML, plus `project.json` for a package add, plus project settings if `UseLocalServer` lives there) — ask file-by-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.
+
+Environment-only fixes (Branch A package install on the robot, Branch E AVX2/VC++/reinstall) are not source-file edits — present them as remediation steps for the operator; no `AskUserQuestion` gate is required for those.
+
+## Stop / escalate
+
+If the message is matched, the corroborating evidence holds, and the prescribed fix is applied (package present, valid `Server`+`ApiKey` or `OCREngine`, window open and selector resolving, AVX2+VC++ present, child inside a real scope) **and the scope still faults at entry**, the cause is outside scope setup — escalate (machine/driver issue, LocalServer install corruption, or a Server-side fault during the child's first analysis call → re-route to [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md)) rather than continue under this playbook. Do not recommend a second config change the evidence does not support.

package/skills/uipath-troubleshoot/references/activity-packages/cv-activities/playbooks/cv-scroll-search-failures.md

@@ -0,0 +1,114 @@
+---
+confidence: medium
+---
+
+# CV scroll-search failures (scrolled entire screen, scroll not reaching pane, silent scroll skip)
+
+## Context
+
+Scroll-search is the mode where a CV find activity (`ScrollDirection != None`) scrolls the target while re-analyzing, searching for the descriptor off-screen. One shared mechanism backs all the find activities; its terminal "covered the whole screen, no match" condition has its own hardcoded (non-localized) message. The same mechanism also fails in three quieter ways: it can throw a raw driver exception while sending scroll input, it can degrade silently to plain in-place retries when the scope root isn't a CV driver element, and (Get Text only) it can fault during scrollable OCR extraction.
+
+What this looks like — the terminal scroll-exhausted message, verbatim:
+
+- `Scrolled the entire screen, but element was not found` — thrown as `UiPath.CV.ElementNotFoundException`. Hardcoded English, no resource key, so it does **not** localize — match the literal regardless of Studio language. Trap: this is a different message from the plain not-found error (`cv-element-not-found.md`); the word `Scrolled` is the discriminator. If you only see a generic not-found message with no `Scrolled`, scroll-search was never engaged — that is a different playbook.
+
+What activities can produce this:
+- **CV Click** (`CvClickWithDescriptor`), **CV Type Into** (`CvTypeIntoWithDescriptor`), **CV Get Text** (`CvGetTextWithDescriptor`) — fault with the `Scrolled the entire screen...` exception, or with a raw driver exception during scroll input.
+- **CV Element Exists** (`CvElementExistsWithDescriptor`) — catches `ElementNotFoundException` and converts it to `Result = false`. The `Scrolled the entire screen...` message is **swallowed** — it never surfaces. ElementExists returning `false` after a configured scroll search is the only symptom; there is no exception to match.
+
+`ScrollDirection`, `NumberOfScrolls` (default 2), and `DelayScreenshotAfterScroll` (default 250 ms) are arguments on the activity. `ScrollOffset` is a property on the enclosing **CV Screen Scope** (`CVScope`), not on the activity.
+
+What can cause it:
+- **Element genuinely absent from the scrollable content.** It is not anywhere in the scrollable region for any scroll position. The mechanism scrolls until two consecutive screenshots produce an identical CV element set (compared via `SequenceEqual`), resets once (see below), confirms unchanged again, then throws. Genuine absence is the default conclusion only after the input-delivery and direction causes below are ruled out.
+- **Wrong `ScrollDirection` for the layout.** Scrolling vertically when the element is reached by horizontal scroll (or vice versa). The covered axis never reveals the element.
+- **Scroll input never reaches the scrollable pane.** The scroll point is computed from the scope center plus `CVScope.ScrollOffset`. If the center+offset lands on a non-scrollable region (a toolbar, a margin, a sibling pane), the mouse-wheel events go nowhere — the screen never changes, so the mechanism declares "entire screen covered" almost immediately. Common with an embedded scroll pane that is not under the scope center.
+- **`NumberOfScrolls` too large.** Each pass scrolls `NumberOfScrolls` notches before re-screenshotting. Too many notches jump the element completely past the viewport between screenshots, so it is never captured in a frame.
+- **`DelayScreenshotAfterScroll` too short for the app.** The screenshot is taken before the app finishes repainting after the scroll; the analyzed frame is stale/blank. Less common; suspect on slow or animated UIs.
+
+What to look for:
+- The activity has `ScrollDirection` set to something other than `None`. If it is `None`, scroll-search is not engaged — route to `cv-element-not-found.md`.
+- Whether the failure is near-instant (screen never changed → input not reaching the pane / wrong scroll point) vs. after a visible scroll sweep (covered the area → genuine absence or wrong direction).
+
+> **Different cause, do not apply this playbook:**
+> - Generic not-found with no `Scrolled` in the message, or `ScrollDirection = None` — the descriptor never matched within timeout without scrolling. Use [cv-element-not-found.md](./cv-element-not-found.md).
+> - Cell-targeting messages (`Could not find table...`, `Invalid row number...`, `Table only contains...`) — use [cv-cell-targeting-failures.md](./cv-cell-targeting-failures.md).
+> - CV Get Text returns empty/stale/wrong text but the activity **succeeded** (no fault) — use [cv-get-text-empty-or-wrong-result.md](./cv-get-text-empty-or-wrong-result.md).
+> - `Invalid Descriptor` / `Target must be set` — descriptor is malformed before any find runs. Use [cv-invalid-descriptor.md](./cv-invalid-descriptor.md).
+> - 401/403/429/5xx, payload/word-limit, or network errors during analysis — the CV server failed, not scrolling. Use [cv-server-auth-throttling-network.md](./cv-server-auth-throttling-network.md).
+> - CV Screen Scope itself failed to set up (target window, server/OCR config) — use [cv-scope-setup-failures.md](./cv-scope-setup-failures.md).
+> - ElementExists false-negative/positive traps unrelated to scroll, or `InRegion` bypass and `ContinueOnError` swallow patterns — use [cv-silent-failures-and-false-results.md](./cv-silent-failures-and-false-results.md).
+
+## Investigation
+
+1. **Confirm scroll-search was engaged.** Read the faulted activity's `ScrollDirection` from XAML. If `None`, stop — this is not a scroll failure; use `cv-element-not-found.md`. If non-`None`, continue.
+2. **Classify by the observable evidence** and route to the matching Resolution branch:
+   - Fault message contains `Scrolled the entire screen, but element was not found` → Branch A.
+   - A faulted CV activity with **no** CV-level message — a raw driver/COM exception (or `NullReferenceException`) whose stack passes through scroll input (`WriteText` / `MouseScroll`) → Branch B.
+   - No scroll motion observed at all and the failure is a plain not-found despite `ScrollDirection != None` — scroll-search degraded to in-place retries → Branch C.
+   - CV Get Text faulting from scrollable content extraction (`Scroll = true` + OCR method) with an externally-originated exception → Branch D.
+   - CV Element Exists returns `Result = false` after a configured scroll search, no exception → Branch E.
+3. **Read the scroll knobs.** Capture `ScrollDirection`, `NumberOfScrolls`, `DelayScreenshotAfterScroll` from the activity and `ScrollOffset` from the enclosing CV Screen Scope. These feed the Branch A decision.
+4. **Establish whether the screen changed during the search.** A near-instant `Scrolled the entire screen...` (no visible scroll motion in any screenshot/recording) means the screen content never changed → input not reaching the pane. A failure after a visible top-to-bottom sweep means the area was genuinely covered.
+
+## Resolution
+
+Walk the branches in order; pick the first whose evidence holds. Branch A is itself a decision tree because one message masks several root causes.
+
+### Branch A — `Scrolled the entire screen, but element was not found`
+
+The mechanism declares the scrollable area fully covered. Sub-cause keyed on observable evidence:
+
+- **A1 — Screen never changed during the search (input not reaching the pane).** Evidence: the failure is near-instant; no scroll motion appears in any captured frame; the scrollable content is an embedded pane not centered under the scope. **Cause.** Scroll point = scope center + `CVScope.ScrollOffset` landed on a non-scrollable region. **Fix:** set/tune `CVScope.ScrollOffset` so the computed point falls inside the scrollable pane, or tighten the CV Screen Scope so its center sits over the pane. Do **not** raise `NumberOfScrolls` here — the wheel events are not landing at all.
+- **A2 — Wrong axis.** Evidence: the element is reached by the opposite scroll axis in the live app (horizontal vs. vertical). **Fix:** set `ScrollDirection` to the axis that actually reveals the element.
+- **A3 — Element skipped between screenshots.** Evidence: a visible scroll sweep occurred, the element is known to exist, and `NumberOfScrolls` is high (well above the default 2). **Cause.** Each pass scrolls too far; the element flashes past the viewport between captures. **Fix:** lower `NumberOfScrolls` (start at the default 2). If the app repaints slowly, also raise `DelayScreenshotAfterScroll` above the 250 ms default so each frame is fully rendered before analysis.
+- **A4 — Element genuinely absent.** Evidence: a full visible sweep occurred, `ScrollOffset`/direction are correct, `NumberOfScrolls`/`DelayScreenshotAfterScroll` are sane, and the element is not present at any scroll position when checked manually. **Cause.** The element is not in the scrollable content (filtered out, wrong record set, not yet loaded). **Fix:** this is not a scroll-tuning problem — verify upstream data/state that should have produced the element. Do not keep adjusting scroll knobs.
+
+> **Reset side effect — confirm before recommending a knob change.** When the screen stops changing, the mechanism resets scroll position once before giving up: it **types `Ctrl+Home` / `Ctrl+End` into the target application** (and may issue up to 500 reverse-scroll notches). On apps where `Ctrl+Home` / `Ctrl+End` do something other than scroll-to-edge (a custom editor, a shortcut binding), this is a real, observable side effect of the failing run — note it to the user. It is not the cause of the not-found, but it explains unexpected app state after the fault.
+
+### Branch B — Scroll input simulation failure (raw driver exception)
+
+Evidence: the CV activity faulted with a driver/COM exception (type depends on the UI driver) or a `NullReferenceException`, and the stack passes through scroll input — the reset `WriteText` (`Ctrl+Home`/`Ctrl+End`) or `MouseScroll`. There is **no** CV-level message; the raw driver exception propagates. This is thrown outside the find try/catch and is not an `ElementNotFoundException`, so the activity faults rather than retrying.
+
+**Cause.** The driver could not deliver synthesized scroll/keyboard input to the target, or the top-parent element had no resolvable absolute position (null `TopParent`) when the scroll point was computed.
+
+**Fix:** confirm the target window is foreground, visible, and not blocked (locked session, secure desktop, UAC prompt, RDP/console mismatch) — the same input-delivery prerequisites as [cv-action-failed-after-find.md](./cv-action-failed-after-find.md). If the `NullReferenceException` recurs on a scope whose target window resolution is unstable, treat it as a scope-setup problem ([cv-scope-setup-failures.md](./cv-scope-setup-failures.md)). Do not retry blindly.
+
+### Branch C — Scroll silently skipped (scope root is not a CV driver element)
+
+Evidence: `ScrollDirection != None`, but **no scroll motion ever occurs**, and the activity ends in a plain not-found at timeout. Common in non-standard sessions — image-based or remote/test sessions where the scope root is not a live CV driver element.
+
+**Cause.** The scroll routine returns immediately when the scope root is not a CV driver element (or when the direction resolves to `None`). Scroll-search degenerates into plain in-place retries until `TimeoutMS`, then reports not found. The element is never searched off-screen.
+
+**Fix:** scroll-search is not available against this scope root. Either run against a live (driver-backed) target window so scrolling works, or stop relying on scroll-search and ensure the element is on-screen before the find (scroll the app via a separate step). Confirm `ScrollDirection` is genuinely non-`None` and not being overridden to `None` at runtime. Do **not** tune `NumberOfScrolls`/`ScrollOffset` — they are never read on this path.
+
+### Branch D — Scrollable content extraction failure (CV Get Text, `Scroll = true` + OCR)
+
+Evidence: `CvGetTextWithDescriptor` with `Scroll = true` and an OCR method type, faulting during the scroll-capture/stitch phase with an exception that originates outside the CV package.
+
+**Cause.** Scrollable extraction is delegated to an external extraction service. Two distinct failure points: (1) the service throws during scroll-capture/stitch and the exception propagates verbatim; (2) the service is resolved at activity construction — a missing registration faults at instantiation, before find. Also note: this extraction phase receives the raw workflow cancellation token, **not** the `TimeoutMS`-bound token — so `TimeoutMS` does **not** bound it. A hang here will not time out via `TimeoutMS`; rule out "raise TimeoutMS" as a fix.
+
+**Fix:** the failing code is in the external extraction/UIAutomationNext service, not the CV activity. Confirm the UIAutomationNext/extraction dependency is present and the package versions are compatible; capture the propagated exception text for the underlying service. If the activity faults at instantiation (before any find), it is a missing service registration — a packaging/dependency problem, not a configuration one.
+
+### Branch E — CV Element Exists returns `false` after a scroll search (swallowed)
+
+Evidence: `CvElementExistsWithDescriptor` with `ScrollDirection != None` returns `Result = false`; no exception in logs.
+
+**Cause.** ElementExists catches `ElementNotFoundException` — including the `Scrolled the entire screen...` case — and converts it to `Result = false`. You cannot distinguish "genuinely absent" from "wrong direction / scroll point / skipped" from the boolean alone; the diagnostic message is gone.
+
+**Fix:** the boolean is not enough evidence to conclude the element is absent. To diagnose, temporarily reproduce the same descriptor and `ScrollDirection`/`ScrollOffset`/`NumberOfScrolls` with a CV Click or CV Get Text (which surface the exception), then apply Branch A. Do not assert "element does not exist" from a `false` ElementExists result when scroll-search is configured — the silent swallow makes a false-negative indistinguishable from a true negative.
+
+## Post-presentation actions
+
+Branches A, B, C, and E may end in edits to the user's workflow files (changing `ScrollDirection` / `NumberOfScrolls` / `DelayScreenshotAfterScroll` on the activity, `ScrollOffset` on the CV Screen Scope, or restructuring the scope). When a recommended fix edits a source file, the resolution is **interactive**. The orchestrator MUST call `AskUserQuestion` before any edit.
+
+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 input, then surface the concrete diff and confirm separately.
+3. **Surface the diff before asking.** Include the file path, the activity `IdRef` (or CV Screen Scope `IdRef`), the property name (`ScrollDirection` / `NumberOfScrolls` / `DelayScreenshotAfterScroll` / `ScrollOffset`), the current value, and the proposed value.
+4. **One question per file/fix.** If both the activity and its enclosing CV Screen Scope change, list both files or ask file-by-file.
+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.
+
+Branch A4 (genuine absence) and Branch D (external extraction/dependency) prescribe no source edit — present the finding without an apply-fix prompt.
+
+## Stop / escalate
+
+If `ScrollDirection` is non-`None`, the scroll point (`CVScope.ScrollOffset`) lands inside the scrollable pane, the direction matches the layout, `NumberOfScrolls`/`DelayScreenshotAfterScroll` are at sane values, the screen visibly changes through a full sweep, and the element still is not captured — the element is genuinely absent from the scrollable content (Branch A4). Stop tuning scroll parameters and investigate the upstream data/state that should have produced it. If Branch B's driver exception or Branch D's external extraction failure persists after the input-delivery and dependency checks above, the fault is outside the CV activity — escalate (UI driver, UIAutomationNext/extraction package, or target-application stability) rather than continue under this playbook.