@uipath/skills 1.195.1 → 1.196.0

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/inject-js-failed.md

@@ -0,0 +1,41 @@
+---
+confidence: medium
+---
+
+# Inject Js Script — Script Missing or Execution Failed
+
+## Context
+
+An `Inject Js Script` activity (`NInjectJsScript`) either had no script to run or the JavaScript failed when executed in the browser.
+
+What this looks like:
+- `Required argument 'Script code' was not provided.` — the `Script code` input was empty/whitespace at runtime.
+- A runtime error surfacing the browser/JavaScript engine's own message — the script was sent to the page but threw or could not run.
+
+What can cause it:
+- The `Script code` input is empty — often a variable/expression an earlier step should have populated.
+- `Script code` is meant to be a path to a `.js` file: when the path can be read, its contents run; when it cannot be read, the value itself is sent to the page as script text and fails as invalid JavaScript. A wrong/missing path therefore surfaces as a JavaScript error, not a "file not found".
+- The JavaScript itself throws (references a missing element/global, syntax error, async assumptions about page state).
+- The activity runs against a target that is not a live web page/DOM, so there is no JavaScript context to execute in.
+- The script's return value cannot be serialized back from the page.
+
+What to look for:
+- Confirm the faulting activity is `Inject Js Script`.
+- Read the `Script code` input: inline script vs file path vs variable, and what it evaluates to.
+- Confirm the activity targets a web page (a `Use Browser` context or a web element).
+
+## Investigation
+
+1. From the failed job, capture whether the message is the missing-`Script code` argument or a JavaScript/browser execution error, plus the activity + workflow.
+2. Read `Script code`. If empty, trace the upstream step that should produce it. If it is a file path, confirm the path resolves on the robot — an unreadable path is run as literal script and fails.
+3. If the script is present, read the browser/engine error: it usually names the offending line, missing reference, or syntax issue.
+4. Confirm the target is a web page with a DOM (the activity needs a browser/JavaScript context).
+5. Check whether the script depends on page state that may not be ready when it runs.
+
+## Resolution
+
+- **Empty `Script code`:** fix the upstream step that should produce it (or supply the script directly when it is static).
+- **File-path script that didn't load:** correct the `.js` path so it resolves on the robot, or inline the script.
+- **JavaScript error:** fix the script — guard for elements/globals it assumes exist, correct syntax, and account for page-load timing (wait for the element/state before injecting).
+- **Non-web target / no DOM:** run the activity against a web page inside a `Use Browser` context; `Inject Js Script` needs a JavaScript context.
+- **Unserializable return:** return a serializable value (string/number/plain object) from the script.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/scope-container-wrong-page.md

@@ -13,6 +13,8 @@ What this looks like:
 - The runtime "closest matches" in the exception belong to a completely different page, locale, or site than the inner selector expects.
 - The scope container has a permissive attach configuration that allows reuse of an unintended existing window/tab.
 
+**Silent variant (no exception).** The wrong-page attach can also produce **no fault at all**: the inner activity runs against the wrong page, its target never matches, yet the job ends `Successful` and the action never happened. This is the "the job succeeded but the button was never clicked" report. It occurs when the miss cannot surface as an exception — e.g. `Simulate` input plus an **absent or target-less Verify Execution** (a `VerifyOptions` with a Mode set but no verification target is inert — "nothing to check" — so the no-op passes silently). There is no exception and no "closest matches" to read; diagnose from source — the scope shape plus the inner activity's Verify Execution config — not from logs. On a silent run the **inert Verify is the confirmed cause of the silent success** (and, when HA was enabled, of why HA never engaged); the **wrong-page attach is only the *likely, unproven* miss cause** — with no exception/closest-matches there is no runtime evidence of which page attached, so do NOT report the scope as a confirmed root cause.
+
 What can cause it:
 - `AttachMode=ByInstance` + default `OpenMode=IfNotOpen`: the container reuses any existing window of the configured app instead of opening the intended URL.
 - `TargetApp.Selector` is permissive (e.g., `<html app='msedge.exe' title='Google' />` matches google.com, google.ro, google.de — any tab whose title contains "Google").
@@ -31,6 +33,7 @@ What can cause it:
    - If the inner selector's `BrowserURL` / page-scoped attribute names a deeper route than `TargetApp.Url`, the scope cannot reach the inner target without explicit navigation.
    - If `TargetApp.Selector` is loose (matches multiple tabs/pages) and `OpenMode=IfNotOpen`, the container will reuse whichever matching tab is already open — typically not the one the developer intended.
 4. Cross-check the runtime exception's `closest matches`: if they belong to a different page than the inner selector expects, the scope landed on the wrong page.
+5. **Silent variant — job `Successful` but the action did not happen.** There is no exception to anchor on. Read the inner activity's **Verify Execution** (`VerifyOptions`) from the XAML: a Mode set with **no verification target** (and default/empty Retry/Timeout) is inert and cannot catch a no-op. Combined with the permissive scope shape from steps 2–3, an inert Verify is the silent-no-op signature — the wrong-page attach succeeded and the unverified inner activity passed without acting.
 
 ## Resolution
 
@@ -41,4 +44,8 @@ Fix the scope container, not the inner selector. Choose ONE:
 - **Insert a `Navigate Browser` / `Go To URL` activity before the inner selector** — keep the current scope, but explicitly drive the attached browser to the intended page before the click/extract. Use when the same scope must service multiple pages in sequence.
 - **Re-record the inner selector against the page the scope actually attaches to** — only when the design intent is to operate on the page the container lands on and the original selector was authored against the wrong page.
 
+**Silent variant — fix priority differs from the faulting case.** With no fault you cannot confirm *why* the click missed (wrong page / fragile selector / timing) — there is no runtime evidence. So the **primary, immediately-actionable fix is to configure Verify Execution** on the inner activity with a real expected-outcome target (an element that exists only after the click) so the next run **faults** instead of silently passing — that makes the failure visible AND surfaces the closest-matches / HA data that will finally prove the miss cause. Configure/enable Verify; never remove or weaken an existing `VerifyOptions`. The four scope fixes above address the *likely* miss but stay **unconfirmed until a fault is produced** — apply them as the follow-up once Verify reveals the real cause, not as the confirmed root-cause fix. Editing the user's workflow XAML is interactive — confirm via `AskUserQuestion` before the edit; do not auto-apply.
+
+**Healing Agent angle — only when HA was activated on the job.** This applies only if `AutopilotForRobots.Enabled = true` AND `HealingEnabled = true` (recommendation or self-healing) and the user expected HA to help. HA engages only on a **fault**; the inert Verify produced none, so HA correctly had nothing to act on. The empty (~22-byte) healing archive and a `Healing agent is disabled for the current job` log line are the **no-trigger state — NOT a configuration or license gate**. Configuring the Verify target is also what gives HA a fault to engage on next time. If instead HA was disabled at the process/job level, the un-helped click is an enablement issue → [selector-failure-healing-disabled.md](./selector-failure-healing-disabled.md), not this silent-no-op path.
+
 Do NOT "fix" the inner selector (adding wildcards, switching to `automationId`, etc.) when the scope is the actual defect. Selector hardening masks the misconfig and leaves the same trap for future activities inside the same scope.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/select-item-no-items.md

@@ -0,0 +1,37 @@
+---
+confidence: medium
+---
+
+# Select Item — Container Has No Items
+
+## Context
+
+A `Select Item` activity (`NSelectItem`) located its target dropdown/list/combo box, but that container held no selectable items at the moment of the action.
+
+What this looks like:
+- Exception class: `UiNodeHasNoItemsException`
+- Friendly message: `The target container does not have any items.`
+- The container WAS found (this is not a selector-not-found) — it is simply empty.
+
+What can cause it:
+- The list is populated by an earlier step (a filter, a dependent dropdown, an API/data load) that did not run, returned nothing, or had not finished when `Select Item` ran.
+- A dependent control: the second dropdown only fills after the first is set, and the first was never set.
+- A timing gap — the action ran before the items rendered.
+- The activity targets the wrong container (a placeholder/empty list rather than the populated one).
+
+What to look for:
+- Confirm the exception is `UiNodeHasNoItems` (container found, empty) — not `NodeNotFound` (a Select Item whose target resolved only via a non-primary search step also surfaces as `NodeNotFound`; that is a selector concern — see the selector-failure playbooks).
+- Trace what is supposed to fill this container before the activity runs.
+
+## Investigation
+
+1. From the failed job, capture the exception, the `Select Item` activity, and the workflow.
+2. Identify the step that should populate the container (filter, dependent selection, data/API load) and confirm it ran and produced items.
+3. Check ordering/timing: did `Select Item` run before the populate step completed or before items rendered?
+4. Confirm the targeted container is the one that gets populated, not an empty placeholder.
+
+## Resolution
+
+- **Upstream populate didn't run / returned nothing:** fix that step — it is the originating fault (the dependent control wasn't set, the query returned no rows, the load failed). `Select Item` cannot choose from an empty list.
+- **Timing:** wait for the items before selecting — add a `Check App State` (Element Exists) on a list item, so `Select Item` runs only once the container is populated.
+- **Wrong container:** retarget `Select Item` to the populated control.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/selector-failure-manual.md

@@ -25,6 +25,7 @@ What to look for:
 - Check if the target application changed recently (version update, UI redesign)
 - Check selector attributes — fragile selectors use title/name, robust selectors use automationId/className
 - If HA data exists but no fix was produced: check eligibility and confidence threshold
+- If the job ended `Successful` yet the action never happened, this is a silent no-op — not a thrown selector failure. Check **Verify Execution**; an absent or target-less Verify is the usual reason no exception surfaced (see [scope-container-wrong-page.md](./scope-container-wrong-page.md))
 
 ## Investigation
 
@@ -42,3 +43,4 @@ What to look for:
 - Update the selector to use more stable attributes (aaname, automationid, role) instead of volatile ones (idx, tableCol, tableRow)
 - Add wildcard matching for dynamic portions: `name='Invoice*'` instead of `name='Invoice_20250319'`
 - Consider adding a Check App State activity before the failing activity to wait for the element
+- If the activity completed `Successful` but never acted (no exception), configure **Verify Execution** on it with a real expected-outcome target so the silent no-op faults and becomes diagnosable — see [scope-container-wrong-page.md](./scope-container-wrong-page.md). Configure/enable Verify; never remove it. Interactive — confirm before editing the workflow.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/timeout-issue.md

@@ -8,10 +8,10 @@ confidence: low
 
 A UI automation activity exceeded its timeout waiting for an element or application state. The default timeout is typically 30 seconds.
 
-TimeoutException is ambiguous — it could be a UI timeout (Check App State, element wait) or a non-UI timeout (HTTP request, queue transaction). Confirm the faulted activity is a UI automation type before following this playbook.
+In modern UIAutomationNext (`N*`) activities a timeout most often surfaces as `RuntimeTimeoutException` ("Activity execution exceeded the set timeout."), or as `NodeNotFoundException` when the element simply never appeared within the wait. Classic activities throw `TimeoutException`, which is ambiguous — it could be a UI timeout (Check App State, element wait) or a non-UI timeout (HTTP request, queue transaction). Confirm the faulted activity is a UI automation type before following this playbook.
 
 What this looks like:
-- Activity waited the full timeout duration and threw TimeoutException
+- The activity waited the full timeout duration and then faulted — modern (`N*`) activities throw `RuntimeTimeoutException`, or `NodeNotFoundException` when the element never appeared within the wait; classic activities throw `TimeoutException`
 - The target element either never appeared or took too long to become interactable
 
 What can cause it:

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/verify-execution-failure.md

@@ -0,0 +1,120 @@
+---
+confidence: high
+---
+
+# Verify Execution Failure — Post-Action Assertion Did Not Hold
+
+## Context
+
+A UI Automation Next interaction activity completed its primary action successfully, but its `VerifyOptions` post-condition check did not hold within the verify retry window. The driver throws `VerifyActivityExecutionException`. The action's side effects are NOT rolled back — the click already clicked, the hover already hovered, the keystrokes were already sent.
+
+Applies to every UIAutomationNext activity that exposes `VerifyOptions`:
+
+- `NClick`
+- `NHover`
+- `NKeyboardShortcuts`
+- `NTypeInto`
+
+This playbook covers the general assertion failure cases (wrong verify target, wrong mode, timeout too short, post-recovery verify failure, action had no visible effect). It does NOT cover `NTypeInto`-specific text-mismatch sub-cases (password fields, special-keys delivery, expected-vs-actual text mismatch, input-disappeared-mid-type) — those have their own friendly-message keys and a separate playbook.
+
+What this looks like:
+
+- Exception class: `UiPath.UIAutomationNext.Exceptions.VerifyActivityExecutionException`
+- Friendly message (generic, this playbook's target): `The element was found but the verification failed because the action did not have the expected outcome.` (resource key `ExceptionCheckActivity`)
+- Other friendly messages this playbook handles:
+  - `The verification failed because the verification target is invalid or not found.` (`ExceptionVerificationTargetNotFoundOrInvalid`)
+  - `The verification failed because the verification target image could not be retrieved.` (`ExceptionVerificationImageCouldNotBeRetrieved`)
+  - `The verification failed because the verification target does not support text attribute.` (`ExceptionVerificationTextNotSupported`)
+  - `The activity execution was recovered by Autopilot, but the verification configured on the activity failed.` (`ExceptionRecoveredButValidationFailed`)
+- Stack origin: `VerifyExecutionService.ExecuteWithVerifyInternalAsync` → `ExecuteWithVerifyAsync` → `<Activity>.ExecuteAsync`
+- Fault duration is close to the verify `Timeout` (default 5s) plus a few retry cycles — the retry loop in `VerifyExecutionService` keeps re-running the assertion until the verify timeout, the activity timeout, or the node becomes invalid.
+- The action itself succeeded — there is NO `NodeNotFoundException` / `SelectorNotFoundException` / `UiNodeDisabledElementException` in the same trace for the failing activity.
+
+What can cause it:
+
+- Verify target selector points at the wrong element, an over-specific element, or an element that only sometimes appears
+- Verify mode (`Appears` / `Disappears` / `TextChanges` / `AspectChanges`) is wrong for the outcome the action actually produces
+- Verify timeout is shorter than how long the asserted state takes to settle (slow page, animation, async navigation)
+- The action's effect is non-deterministic (e.g., "I'm Feeling Lucky" → variable destination), and the verify target presumes a deterministic outcome
+- Autopilot recovery healed the action via an alternate path, and the asserted post-condition is no longer reachable from the recovered state
+- The action landed but had no UI effect (overlay swallowed the click, focus lost between activities, element re-rendered)
+
+What to look for:
+
+- Confirm the exception class is `VerifyActivityExecutionException`. If it is anything else, this playbook does not apply.
+- Confirm the friendly message is one of the keys listed above. If it is `ExceptionCheckActivityPassword`, `ExceptionCheckActivityTypeInto`, `ExceptionCheckActivityTypeIntoWithSpecialKeys`, or `ExceptionCheckActivityTypeIntoInputDisappeared`, use the (planned) `verify-execution-typeinto.md` playbook instead — those are NTypeInto text-match failures with different fixes.
+- Identify the faulting activity name and its workflow file (e.g., `ClickCase.xaml` → `NClick "Click 'Submit'"`).
+- The `VerifyOptions` configuration (Target selector, Mode, Timeout, Retry) is **NOT in job logs or traces** — only in the workflow source. This investigation is **source-required**.
+
+## Investigation
+
+1. From the failed job, capture the exception class, friendly message, faulting activity, and workflow file.
+2. Open the workflow source. Locate the failing activity by name or `IdRef`. Read its full `VerifyOptions` block:
+   - `Mode` (`Appears` / `Disappears` / `TextChanges` / `AspectChanges`)
+   - `Target` — the full selector and any anchors / scope (note the `BrowserURL`, `ScopeSelectorArgument`, `aaname`, `tag`)
+   - `Timeout` — explicit value, or empty `<InArgument x:TypeArguments="x:Double" />` meaning the default (~5s)
+   - `Retry` — `true` / `false` / unset (default `true`)
+3. Read the activity's own `Target` selector and its `InteractionMode` (separate concern, but useful context).
+4. Compare the verify `Target.BrowserURL` / scope to where the action actually lands. If they differ, the action navigates somewhere — verify whether the verify target is realistically reachable from the action's landing page.
+5. Check whether the asserted outcome is deterministic. If the action can produce different end states across runs (search result page, dynamic content, A/B variants), an `Appears` assertion on a specific element is fragile.
+6. Compute the fault duration. If it is approximately the verify `Timeout` value, the retry loop exhausted — the assertion never held. If it is much shorter, an inner failure short-circuited (e.g., verify target selector invalid at parse time).
+7. If Healing Agent ran on this job, check whether the action was *recovered* (the original target was healed) — the recovered action can resolve to a different landing page than the workflow author expected, which can make the verify target unreachable. See [interpretations/healing-agent-data.md](../interpretations/healing-agent-data.md).
+
+## Resolution
+
+### Decision tree
+
+Walk this tree from the top. Stop at the first branch that matches.
+
+1. **Is the friendly message `ExceptionVerificationTargetNotFoundOrInvalid`?**
+   - YES → branch **(A)**. The verify selector itself is bad — fix the selector before doing anything else.
+   - NO → continue.
+
+2. **Is the friendly message `ExceptionVerificationTextNotSupported` or `ExceptionVerificationImageCouldNotBeRetrieved`?**
+   - YES → branch **(B)**. The verify `Mode` is incompatible with the verify target's element type.
+   - NO → continue.
+
+3. **Is the friendly message `ExceptionRecoveredButValidationFailed`?**
+   - YES → branch **(C)**. Autopilot healed the action; the healed path landed somewhere the verify target cannot reach.
+   - NO → continue.
+
+4. **Is the action's outcome non-deterministic** (different runs land on different pages / different DOM)?
+   - YES → branch **(D)**. The verify target presumes a specific outcome that the action does not guarantee.
+   - NO → continue.
+
+5. **Is the fault duration close to the verify `Timeout` AND the asserted state is reachable but slow** (animations, async load, navigation)?
+   - YES → branch **(E)**. Verify timeout is too short for the real settle time.
+   - NO → continue.
+
+6. **Default — the action ran but produced no UI effect** → branch **(F)**. Diagnose why the action did not have its intended consequence (overlay, focus, wrong target).
+
+### Branches
+
+- **(A) `ExceptionVerificationTargetNotFoundOrInvalid` — bad verify selector.** The `VerifyOptions.Target` failed to parse or returned no nodes. Open the verify target in Studio's Object Repository / selector editor. Fix the selector to point at a real, stable element on the post-action page. Common authoring mistakes: pointing verify at the same element as the action (which often disappears after the action); copying a stale design-time selector from a now-changed page; using a selector with a dynamic `idx=` that shifts between sessions. Do NOT remove `VerifyOptions` entirely — re-targeting is the right fix.
+
+- **(B) `ExceptionVerificationTextNotSupported` / `ExceptionVerificationImageCouldNotBeRetrieved` — wrong `Mode` for the element type.** `TextChanges` on an element that does not expose a text attribute (image, canvas, custom non-text control) throws `TextNotSupported`. `AspectChanges` on an element whose bounding rect cannot be captured (offscreen, zero-size, hidden) throws `ImageCouldNotBeRetrieved`. Switch `Mode`:
+  - For text-bearing elements: `TextChanges` or `Appears` (with a target whose text changes drive its presence)
+  - For visual / image elements: `AspectChanges` with a verify target that is on-screen and has non-zero size
+  - For elements that should appear or disappear post-action: `Appears` or `Disappears`
+  If no mode fits the element type, re-target the verify at a different element that does support the desired mode.
+
+- **(C) `ExceptionRecoveredButValidationFailed` — Autopilot recovered the action but verify still fails.** The recovered action landed on a path the verify target cannot reach. Two sub-options:
+  - If the recovery is correct and the verify target is wrong-for-the-recovered-path: update the verify target to match where the recovered action actually lands. The original verify target was specific to the unhealed path.
+  - If the recovery is wrong (healed to a different button than the intended one): treat this as a selector-failure case. Apply the Healing Agent fix from `healing-fixes.json` via Studio Desktop Recovery Panel, or update the action's primary selector so recovery is not invoked. See `selector-failure-healing-fix.md`.
+
+- **(D) Non-deterministic action outcome — verify target is over-specific.** The action can land on different pages / DOMs across runs (search results, "I'm Feeling Lucky", dynamic feeds, A/B-tested layouts). An `Appears` assertion on a single specific element will fail whenever the action lands elsewhere. Fix one of:
+  - **Loosen the verify target** to an element that is present on every reachable post-action page (a navigation bar, footer, page chrome, a meta element). Sacrifices specificity for reliability.
+  - **Switch `Mode` to `AspectChanges`** on a region that is guaranteed to change after the action — verifies *something happened* without asserting *what* happened.
+  - Do NOT extend the timeout — the issue is not slowness, it is non-existence on this run.
+  - **Do NOT remove `VerifyOptions`** to make the exception go away. Stripping the assertion turns a noisy failure into a silent one and weakens the workflow. If no stable verify target exists across all reachable outcomes AND no region is suitable for `AspectChanges`, surface that to the workflow author as a design issue — the action's outcome cannot be asserted and the workflow needs rethinking — instead of deleting the verify block.
+
+- **(E) Verify timeout too short for the real settle time.** The asserted state is reachable but takes longer than the verify timeout to appear/change. Increase `VerifyOptions.Timeout` to a value that comfortably covers worst-case settle (e.g., 10–15s for typical web navigation, 20–30s for app launches or remote workflows). Do NOT extend blindly — first confirm that the verify target *does* eventually appear when the activity is rerun with a longer timeout. If the target never appears regardless of wait, the cause is branch (D) or (F), not timeout.
+
+- **(F) Action had no UI effect — diagnose why.** The action dispatched but the application did not respond. Common causes (investigate in this order):
+  - **Click intercepted by an overlay / popup.** Inspect Healing Agent data for popup detections; add a deterministic dismiss step before the action. See [interpretations/healing-agent-data.md](../interpretations/healing-agent-data.md).
+  - **Wrong element targeted.** The action's selector matched a duplicate or shadow element (off-screen iframe, hidden carousel, ARIA-hidden duplicate). Tighten the action's selector — not the verify target.
+  - **`InputMode` mismatch with target tech.** `Simulate` on a non-HTML host, `HardwareEvents` on a screen region that has moved, `ChromiumAPI` on a non-Chromium frame. The action lands at the OS layer but the application's event handler never fires. Switch `InputMode` to match the target tech.
+  - **Focus lost between activities.** A prior activity left focus on a different app/tab. Add a Use Application / Activate step before the action.
+  - **Timing — DOM not ready.** The action runs against a stale DOM (page was re-rendered between action and verify). Add a Check App State before the action; or set `WaitForReady = COMPLETE` on the action's target.
+
+  Once the action's actual effect is restored, the verify assertion will hold without changes.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/playbooks/wrong-target-application.md

@@ -0,0 +1,41 @@
+---
+confidence: high
+---
+
+# Identified Element Belongs to a Different Application
+
+## Context
+
+The activity resolved an element, but that element does not belong to the application/browser the enclosing scope is bound to. The runtime rejects it rather than acting on an element outside the target application.
+
+What this looks like:
+- Exception class: `WrongTargetApplicationException`
+- Friendly message: `The identified element does not belong to the target application/browser.`
+- The scope (`Use Application/Browser`) attached successfully, but the element acted on (often the focused element or active window) is owned by a different process.
+
+What can cause it:
+- A different window came to the foreground between scope attach and the action (a notification, a popup from another app, the OS stealing focus), and the activity resolves against whatever is focused/active.
+- The scope's application selector is permissive enough to attach to one app while the element the activity finds lives in another (similar titles across apps).
+- Two instances/processes present similar windows and the activity reached the wrong one.
+- On multi-monitor / multi-session machines, a window from another app overlaps or is focused at action time.
+
+What to look for:
+- Confirm the exception is `WrongTargetApplicationException` (the element WAS identified — this is not `NodeNotFound`, and the scope did attach — this is not `ApplicationNotFound` / `ApplicationOpenException`).
+- Identify which activity faulted and whether it operates on the focused element / active window.
+- Read the scope's application selector and how specific it is.
+
+## Investigation
+
+1. From the failed job, capture the exception class, the faulting activity, and the enclosing scope.
+2. Read the scope's `Target application` selector — note whether it is specific to the intended process or loose enough to match another app's window.
+3. Determine whether the failing activity acts on the focused element / active window (these are most exposed to a foreground change at action time).
+4. Check what else runs on the robot at that moment: a popup, notification, or another automation that could steal focus right before the action.
+5. Confirm the intended application was actually in the foreground/owning the element when the activity ran.
+
+## Resolution
+
+- **Foreground/focus stolen by another app:** the originating fault is that the wrong window was active. Trace and remove the focus thief, or ensure the target window is foreground before the action (bring the target to front as part of the legitimate flow, not as a mask). If a popup from another app intrudes, dismiss it deterministically.
+- **Loose application selector:** tighten the scope's application selector to the intended process (use the process/`app` attribute, not just title), or attach via an Object Repository application target so the binding is unambiguous.
+- **Multiple instances:** make the scope attach to the specific intended instance rather than any matching window.
+
+Do not relax the activity to "act on whatever is focused" to make the error disappear — that hides the real foreground/selector problem and lets the robot act on the wrong application.

package/skills/uipath-troubleshoot/references/activity-packages/ui-automation/summary.md

@@ -9,6 +9,18 @@
 | Selector Failure — Manual Investigation | Medium | Selector mismatch requiring manual analysis (HA produced no fix or source code available) | [selector-failure-manual.md](./playbooks/selector-failure-manual.md) |
 | Selector Failure — Scope Container Attached to Wrong Page/Window | Medium | Scope container (`NApplicationCard`, `NBrowser`, `Use Application/Browser`, `NWindow`) attached to a different page/window than the inner selector expects; the selector itself is correct for its intended page | [scope-container-wrong-page.md](./playbooks/scope-container-wrong-page.md) |
 | Disabled Element — AlterIfDisabled Not Enabled | High | `UiNodeDisabledElementException` from any UIAutomationNext interaction activity (NClick, NTypeInto, NSetText, NCheck, NSelectItem, NSAPClickPictureOnScreen) where the target was found but disabled and `AlterIfDisabled` was not set | [disabled-element.md](./playbooks/disabled-element.md) |
+| Verify Execution Failure — Post-Action Assertion Did Not Hold | High | `VerifyActivityExecutionException` from NClick/NHover/NKeyboardShortcuts/NTypeInto where the action succeeded but the `VerifyOptions` post-condition (Appears / Disappears / TextChanges / AspectChanges) did not hold. Covers wrong verify target, wrong mode, timeout too short, post-recovery verify failure, action-had-no-effect. NTypeInto text-mismatch sub-cases not included. | [verify-execution-failure.md](./playbooks/verify-execution-failure.md) |
+| Click Coordinate Off-Screen — HardwareEvents | High | Input activity (`NClick`, `NTypeInto`, ...) faulted with `UiAutomationException: "Cannot send input to UI element because it is outside of screen bounds."` because `InteractionMode=HardwareEvents` requires an on-screen coordinate but the design-time-captured coordinate falls outside the runtime host's virtual screen. Element was located; coordinate rejected. | [click-coordinate-off-screen.md](./playbooks/click-coordinate-off-screen.md) |
+| Ambiguous Selector — Target Matched Multiple Elements | High | `NodeAmbiguousException` from any UIA-Next activity that resolves a target. Selector matched MORE than one element — too generic, repeated UI pattern, multiple windows of the same app, dynamic-attribute drift, iframe / shadow-root double traversal, or a dialog hoisting a duplicate. Distinct from `NodeNotFoundException` (zero matches). Healing Agent explicitly bypasses this exception — no recovery data is produced. | [ambiguous-selector.md](./playbooks/ambiguous-selector.md) |
 | Timeout Issue | Low | UI automation activity exceeded its timeout waiting for an element or application state | [timeout-issue.md](./playbooks/timeout-issue.md) |
+| Healing Agent — Orchestrator Status, Logs & Notifications (Is This Expected?) | High | "Is this expected?" disambiguator for 4 Orchestrator-side HA surfaces, routed by where the customer saw it: (1) Jobs-grid `Issues Detected` / tab "Unlicensed version" banner, (2) Info log `Healing agent configuration.` (benign config read), (3) email/in-app Notification Summary (real HA event), (4) `No available license / Agentic units` informational notice. Covers preview UIA `24.10.x` detecting/alerting unlicensed + the shared "does this consume units?" rule. Real no-license error → healing-agent-no-license.md | [healing-agent-orch-issues.md](./playbooks/healing-agent-orch-issues.md) |
 | Healing Agent — No License / Heals Available | High | Robot log contains `"No available license / Agentic units to perform healing analysis and recovery"` (or, corroborating: HA enabled + 22-byte healing-data ZIP + `Allowed.AgentService == 0`) | [healing-agent-no-license.md](./playbooks/healing-agent-no-license.md) |
 | Healing Agent — No Recovery Data | Low | Healing Agent enabled but no recovery data generated after failure (license OK; connectivity / classic activity / image-only target) | [no-recovery-data.md](./playbooks/no-recovery-data.md) |
+| Application Not Found | High | `ApplicationNotFoundException` thrown by `NApplicationCard` (Use Application / Use Browser) when target app can't be located and `OpenMode=Never`. Covers `OpenMode` misconfiguration, selector drift, crashed-app, no-visible-window, cold-start race. Distinct from `ApplicationOpenException` (launch attempted) and `WrongTargetApplicationException` (wrong window matched). | [application-not-found.md](./playbooks/application-not-found.md) |
+| Application Could Not Open — Launch Failed | High | `ApplicationOpenException` ("Could not open target application.") — a `Use Application/Browser` scope with `Open` ≠ `Never` tried to launch the app and failed (missing executable, blocking startup dialog, browser/WebDriver, permissions) | [application-open-failed.md](./playbooks/application-open-failed.md) |
+| Identified Element Belongs to a Different Application | High | `WrongTargetApplicationException` ("The identified element does not belong to the target application/browser.") — the element acted on is owned by a different process than the scope's target (foreground/focus change, loose application selector) | [wrong-target-application.md](./playbooks/wrong-target-application.md) |
+| Go To URL — Navigation Failed | Medium | `Go To URL` (`NGoToUrl`) could not navigate: missing `URL`, `BrowserInvalidURLException`, `BrowserFailedToNavigateToUrlException`, or a local `file://` blocked on Chromium | [browser-navigation-failed.md](./playbooks/browser-navigation-failed.md) |
+| Inject Js Script — Script Missing or Execution Failed | Medium | `Inject Js Script` (`NInjectJsScript`) with empty `Script code`, or the JavaScript threw / could not run in the browser | [inject-js-failed.md](./playbooks/inject-js-failed.md) |
+| Activity Configuration Error — Invalid Property Value | High | An activity faulted on its own property validation: Mouse Scroll `Movement units` < 1 or missing searched element, Keyboard Shortcuts empty/invalid sequence, Take Screenshot missing `File name` / `Saved image` | [activity-configuration-error.md](./playbooks/activity-configuration-error.md) |
+| Element Found But Not Actionable | Medium | Element located but stale (`InvalidNodeException` / `UiNodeUninitializedElementException`), not visible (no screen rectangle / `TargetFoundButNotVisibleException`), or blocked by a browser dialog (`TargetNotFoundBrowserBlockedException`) | [element-found-not-actionable.md](./playbooks/element-found-not-actionable.md) |
+| Select Item — Container Has No Items | Medium | `UiNodeHasNoItemsException` ("The target container does not have any items.") — Select Item's dropdown/list was empty at action time | [select-item-no-items.md](./playbooks/select-item-no-items.md) |

package/skills/uipath-troubleshoot/references/products/agents/playbooks/guardrail-violation.md

@@ -0,0 +1,111 @@
+---
+confidence: high
+---
+
+# Guardrail Violation
+
+## Context
+
+What this looks like:
+- Agent job faults; `uip agent run status <job-id> --output json` shows `Faulted`
+- `agentRun` span has `AGENT_RUNTIME.TERMINATION_GUARDRAIL_VIOLATION` in `attributes.error`
+- Container span (`agentPreGuardrails`, `llmPreGuardrails`, `toolPreGuardrails`, `agentPostGuardrails`, `llmPostGuardrails`, `toolPostGuardrails`) carries the blocking error
+- Child `guardrailEvaluation` or `toolGuardrailEvaluation` span identifies the rule: `guardrailName`, `action`, `validationResult`, `reason`
+
+Classification table — container span type identifies scope and stage:
+
+| Container span | Stage | Data validated |
+|---|---|---|
+| `agentPreGuardrails` | pre (input-side) | agent invocation payload |
+| `llmPreGuardrails` | pre (input-side) | LLM prompt / messages |
+| `toolPreGuardrails` | pre (input-side) | tool call arguments |
+| `agentPostGuardrails` | post (output-side) | agent response |
+| `llmPostGuardrails` | post (output-side) | LLM response |
+| `toolPostGuardrails` | post (output-side) | tool call result |
+
+What can cause it:
+- Block action matched content in invocation payload, LLM prompt/response, or tool call arguments/result
+- Escalate action fired and Action Center reviewer rejected the task
+- Recent rule tightening or action change from Log/Escalate to Block — behavior change is immediate and silent
+- Overly broad pattern matches legitimate content (common business terms, structured JSON fields)
+- OOB validators (PII detection, harmful content, prompt injection, user prompt attacks) at agent or LLM scope — these run automatically when enabled and require no custom rules
+
+> **Filter and Log do not fault the job.** Filter removes `excludedFields` from the payload; `updatedInput`/`updatedOutput` appear on the evaluation span; execution continues. Agent may behave unexpectedly if required fields are stripped. Log records the match; `severityLevel` appears on the evaluation span; execution continues. Neither produces `TERMINATION_GUARDRAIL_VIOLATION`.
+
+> **Distinct error shape — governance policy:** If the error is `"User is forbidden by governance policy to use: <model>"` (`StatusCode 403`, `ErrorCode 3000`), this is an Automation Ops model-restriction policy, not a guardrail rule. Check via: `uip gov aops-policy deployed-policy get <license-type> AITrustLayer <tenant-id> --output json`
+
+## Investigation
+
+1. Get trace ID:
+
+   ```bash
+   uip agent run status <job-id> --output json \
+     --output-filter "traceId"
+   ```
+
+2. Find erroring spans, identify container span, classify pre/post using the table above. If the only erroring span is `agentRun` and no container guardrail span appears in the results, the termination error propagated from a child evaluation — proceed to step 3 to find the `guardrailEvaluation` or `toolGuardrailEvaluation` span directly:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?attributes.error != null].{spanType: spanType, error: attributes.error, name: name}"
+   ```
+
+3. Read the `guardrailEvaluation` or `toolGuardrailEvaluation` child span for `guardrailName`, `action`, `validationResult`, `payload`, and `reason`:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?spanType == 'guardrailEvaluation' || spanType == 'toolGuardrailEvaluation'].{spanType: spanType, guardrailName: attributes.guardrailName, action: attributes.action, validationResult: attributes.validationResult, payload: attributes.payload, reason: attributes.reason}"
+   ```
+
+4. Inspect the triggering rule:
+
+   ```bash
+   uip agent guardrails list --output json \
+     --output-filter "[?contains(Validator, '<GUARDRAIL_NAME>')].{validator: Validator, scopes: AllowedScopes, stages: GuardrailStages, status: Status}"
+   ```
+
+   Replace `<GUARDRAIL_NAME>` with guardrailName value from step 3.
+
+   Then fetch catalog entry:
+
+   ```bash
+   uip agent guardrails catalog --validator <validator-id> --output json
+   ```
+
+   For custom guardrails (rule logic in agent definition):
+
+   ```bash
+   uip agent config get guardrails --path <PROJECT_DIR> --output json
+   ```
+
+   To confirm action type and last-modified date: open agent in AgentBuilder or Flow → Guardrails → find rule by name from step 3 (optional — confirms action type and last-modified date; CLI output above is sufficient to identify the rule).
+
+5. Escalate action only — check reviewer outcome:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?spanType == 'guardrailEscalation' || spanType == 'toolGuardrailEscalation'].{spanType: spanType, reviewOutcome: attributes.reviewOutcome, reviewStatus: attributes.reviewStatus, reviewedBy: attributes.reviewedBy}"
+   ```
+
+   `reviewOutcome: "Rejected"` means reviewer rejected → faults the job. Absent or pending span means the Action Center task is still open.
+
+## Resolution
+
+**Block + legitimate violation:** Fix caller payload (pre/input-side container span) so it does not contain prohibited content before sending. For post/output-side violations, tighten system prompt in `agent.json → messages[0].content` to constrain LLM output (e.g., "Respond only in JSON. Do not include names or email addresses.").
+
+**Rule too broad:** Narrow the pattern in AgentBuilder or Flow → Guardrails. For centralized guardrails enforced by a tenant admin: Automation Ops → Governance → AI Trust Layer → find policy by name from step 3. Replace the overly broad expression with a more specific match. Re-test with the previously blocked input.
+
+**Action changed from Log/Escalate to Block:** Revert the action in AgentBuilder or Flow → Guardrails if the prior review workflow is still required. Or keep Block and fix the underlying data (system prompt or rule narrowing above).
+
+**Escalate reviewer rejected:** Determine if rejection was correct or reviewer error. If reviewer error, re-invoke agent to create new Action Center task. If rule intent is issue, adjust rule or fix data handling before re-invoking.
+
+**Filter causing unexpected behavior (not a fault):** Inspect `updatedInput`/`updatedOutput` on the evaluation span from step 3 to see which fields were removed. Verify the agent handles absent fields gracefully. Add fallback logic if required fields can be stripped.
+
+**Recent rule regression:** Check last-modified date in AgentBuilder or Flow → Guardrails. Restore the prior rule definition or disable the rule temporarily. Document the rollback and review rule scope with the guardrail policy team.
+
+Validate and republish after any rule or agent change:
+
+```bash
+uip agent validate --output json
+uip solution publish --output json
+```

package/skills/uipath-troubleshoot/references/products/agents/playbooks/is-connection-disabled.md

@@ -0,0 +1,90 @@
+---
+confidence: medium
+---
+
+# IS Connection Disabled (403)
+
+## Context
+
+What this looks like:
+- Agent job faults during an IS tool call; `uip agent run status <job-id> --output json` shows `Faulted`
+- `uip traces spans get <trace-id> --output json` contains a `toolCall` span whose `ATTRIBUTES.error` contains:
+  ```
+  Your connection has been temporarily disabled due to multiple unsuccessful attempts. To restore access, please reauthenticate
+  ```
+  or `Failed to execute IS Event call: HTTP Status: 403 - Forbidden`
+- Error appears on first IS call in the run; no successful IS calls precede it
+- Applies to OAuth2 authorization code connections only — client credentials flows are not affected by this lockout mechanism
+
+What can cause it:
+- IS disabled the connection after failing consecutively to refresh the token (protective lockout)
+- Repeated IS health-check failures cascaded into a lockout independently of credential validity
+- Connected app credentials (OAuth client secret, API key) were rotated on the external system after the connection was created
+- An IS administrator manually disabled the connection
+
+What to look for:
+- Whether the error says "temporarily disabled due to multiple unsuccessful attempts" (lockout) vs. a generic 403 (external system permissions changed)
+- Whether other automations using the same IS connection started failing at the same time — shared lockout vs. single-agent issue
+- The connection name or ID in the span — needed to target the re-authentication command
+- The IS connection list may show the connection as "Connected" even when it is locked out — `uip is connections ping` is required to confirm the actual state
+
+## Investigation
+
+1. Get the job trace ID:
+
+   ```bash
+   uip agent run status <job-id> --output json \
+     --output-filter "traceId"
+   ```
+
+2. Find the faulting `toolCall` span and extract IS connection details:
+
+   ```bash
+   uip traces spans get <trace-id> --output json \
+     --output-filter "spans[?attributes.error != null].{name: name, spanType: spanType, error: attributes.error}"
+   ```
+
+   Note the connection name or ID from the error text or span name.
+
+3. List IS connections to identify the connection:
+
+   ```bash
+   uip is connections list --output json \
+     --output-filter "connections[?name == '<connection-name>'].{id: id, name: name, connector: connector}"
+   ```
+
+4. Ping the connection to confirm lockout:
+
+   ```bash
+   uip is connections ping <connection-id> --force-refresh --output json
+   ```
+
+   A failed ping or authentication error confirms the lockout.
+
+## Resolution
+
+**If locked out — re-authenticate:**
+
+  ```bash
+  uip is connections edit <connection-id>
+  ```
+
+  Completes OAuth re-authentication in the browser, lifting the lockout.
+
+**If credentials were rotated on the external system — update credentials and re-authenticate:**
+
+  On the external system (e.g., Salesforce > Connected Apps), regenerate the client secret. Then:
+
+  ```bash
+  uip is connections edit <connection-id>
+  ```
+
+  Complete the OAuth flow with the new credentials.
+
+**If manually disabled by an administrator:**
+- Coordinate with the admin — re-authenticate only after root cause of repeated failures is resolved
+- Once approved: `uip is connections edit <connection-id>`
+
+**If lockout recurs within hours after re-authentication — escalate:**
+
+  Recurring lockouts indicate an underlying connector-level issue (misconfigured OAuth scopes, provider-side rate restriction, or external system instability) that re-auth temporarily masks. Capture the connection ID and the recurrence pattern, then escalate to the Integration Service team — `uip is connections edit` alone will not resolve this.