@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-com-start-background-session0.md

@@ -0,0 +1,50 @@
+---
+confidence: medium
+---
+
+# Word Application Scope — COM Start Fails in Background / Session 0 (unattended)
+
+## Context
+
+What this looks like:
+- `Word Application Scope` / `Use Word File` faults on **COM start**, before any document is opened.
+- Exception type `UiPath.Word.WordException`, message `Error opening document, make sure Word application is installed. If already installed, an Office Repair may be required.`
+- Stack runs through the COM-start path:
+  - `UiPath.Word.Windows.Utilities.WordAppHelpers.StartNewApplication`
+  - `UiPath.Word.Windows.Utilities.ComAppReferenceCountManager.StartOrAttach`
+  - `UiPath.Word.Activities.WordApplicationScope.Execute`
+- The job is typically **unattended** (Orchestrator-dispatched on a robot machine). A common tell: Word opens fine when a user launches it interactively on the same machine, but the unattended robot fails.
+- Distinct from the open-path `COMException "Command failed"` (faults on `Documents.Open`; see [word-open-sharepoint-url-com-command-failed.md](./word-open-sharepoint-url-com-command-failed.md)) and from the wrong-thread cast (`0x8001010E`; see [word-export-pdf-com-wrong-thread.md](./word-export-pdf-com-wrong-thread.md)).
+
+What can cause it (more than one may apply):
+- **Background Process / Session 0 (primary).** The process is published as a Background Process, so on an Unattended Robot it runs in **Session 0** under `LOCAL SERVICE` with no interactive desktop. Microsoft Office apps (Word/Excel/PowerPoint) are user-session apps — their COM server can only instantiate inside an interactive Windows session, so `StartNewApplication` fails. The project-side marker is `runtimeOptions.requiresUserInteraction: false` in `project.json` (equivalently, **Project Settings → Starts in Background = Yes**). **Note: modern `project.json` has no `"background": true` key — `requiresUserInteraction: false` is the flag.**
+- **Word not installed / not COM-capable** on the robot machine — no supported Word desktop edition, or a non-interop install. The error's first clause ("make sure Word application is installed") points here; confirmed only when Word does *not* open interactively for the robot user.
+- **Broken Office COM Interop registration** — install/uninstall/downgrade or component (e.g. Skype for Business) mismatch left Word mis-registered; needs an Office Repair. This fails **both** interactively and unattended, so it is ruled out when Word opens cleanly in an interactive session.
+
+What to look for:
+- `runtimeOptions.requiresUserInteraction` in `project.json` (`false` ⇒ background process).
+- Whether the run is unattended Session 0 / background vs attended / interactive.
+- Whether Word opens standalone for the robot user on the affected machine (host-side check).
+
+## Investigation
+
+1. Read the error from job evidence. Confirm the type is `UiPath.Word.WordException` with the "make sure Word application is installed … Office Repair may be required" text and the top frame is `WordAppHelpers.StartNewApplication` (COM start) — not `Documents.Open` and not a child cast.
+2. Read `runtimeOptions.requiresUserInteraction` from `project.json`. `false` confirms the process is a Background Process that runs in Session 0 when unattended. Do NOT look for a `"background": true` key — it does not exist in modern `project.json`.
+3. Establish the run surface: unattended Orchestrator job in background / Session 0 vs attended / interactive session. The job's robot/machine and session type are in the job evidence.
+4. Host-side discriminators (out-of-band — ask the user, not reachable via CLI): (a) Does a supported Word desktop edition open standalone for the robot user (`Win+R → winword`)? (b) Does the Studio Repair Tool for Microsoft Office *detect* Word? Answers split the causes:
+   - Word **opens interactively** but the **background** robot fails ⇒ Background/Session-0 limitation (primary cause).
+   - Word **does not open** / is absent ⇒ not installed.
+   - Word **errors interactively too** / Repair detects a problem ⇒ broken registration.
+
+## Resolution
+
+- **If `requiresUserInteraction: false` / Background Process / Session 0 (Word opens interactively):**
+  - Publish the process as a **foreground** process: Studio **Project Settings → Starts in Background → No** (sets `runtimeOptions.requiresUserInteraction: true`), so the Office activities run in an interactive session.
+  - Configure the unattended robot to open an **interactive Windows session** — a Service Mode Robot using a robot account with Unattended setup and **Windows credentials** (so it auto-logs-on an interactive session), rather than a headless background run.
+  - If the process must stay background, wrap the Office activities in a **Use Foreground** activity, which temporarily moves execution into the foreground.
+  - **Do NOT run an Office Repair** — install and registration are healthy when Word opens cleanly interactively.
+  - Confirm with an out-of-band A/B re-run: foreground / interactive run succeeds vs the background run faulting.
+- **If Word is not installed / not COM-capable** on the robot machine: install a supported Microsoft Word desktop edition (interop-capable) for the robot user.
+- **If Office COM registration is broken** (Word errors interactively too): run the **Repair Tool for Microsoft Office** (Studio → Home → Tools → Apps) on the robot machine.
+
+If the failure persists after the process runs foreground in a confirmed interactive session with Word installed and registered, capture a `Verbose` robot log plus the full stack and open a UiPath support case.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-export-pdf-com-wrong-thread.md

@@ -0,0 +1,46 @@
+---
+confidence: medium
+---
+
+# Word Application Scope — Save Document as PDF COM Wrong-Thread (0x8001010E RPC_E_WRONG_THREAD)
+
+## Context
+
+What this looks like:
+- `Save Document as PDF` (`WordExportToPdf`) — or another activity inside the surrounding `Word Application Scope` / `Use Word File` — faults casting the document COM object.
+- Error message contains:
+  - `Unable to cast COM object of type 'System.__ComObject' to interface type 'Microsoft.Office.Interop.Word._Document'.`
+  - `... the QueryInterface call on the COM component for the interface with IID '{0002096B-0000-0000-C000-000000000046}' failed ...`
+  - `The application called an interface that was marshalled for a different thread. (0x8001010E (RPC_E_WRONG_THREAD)).`
+- IID `{0002096B-0000-0000-C000-000000000046}` = `Microsoft.Office.Interop.Word._Document`.
+- The workflow is often structurally correct — the export is the sole/last child of the scope that opened the document, with no `Parallel`/`Pick`/`Invoke`/coded thread between scope-open and export.
+
+What can cause it (more than one may apply):
+- **Scope attached to an externally-owned Word instance** — Word (`WINWORD.EXE`) was already open when the scope ran. `Word Application Scope` exposes no new-instance / isolated-instance / attach control (unlike `Excel Process Scope`), so it reuses the running Word. That instance's `_Document` lives on the external process's STA apartment; the robot worker thread's cross-apartment `QueryInterface` fails.
+- **The attached Word closed mid-run** — the externally-owned Word window closed (manually, by a user, by another process, or by an embedded OLE host) after the scope bound the document but before the export. The close tore down / re-marshalled the apartment owning the `_Document`, leaving the activity's proxy bound to a stale/replaced apartment. `RPC_E_WRONG_THREAD` (not `0x80010108 RPC_E_DISCONNECTED`) is the signature of a *replaced* apartment, not a clean server death.
+- **Off-STA / non-interactive runtime** — the export ran where the worker thread is not the STA that owns the document: an unattended robot in Session 0, a background process, or a thread other than the scope creator (`Parallel`/`Pick`/async/`Invoke Code`/coded `.cs`). Word interop requires an interactive STA session.
+- **Package version skew** — a pre-release / alpha `UiPath.Word.Activities` build on a runtime it was not paired with. Alpha-build behavior is undefined; rule it out by testing the stable LTS-bundled version.
+
+What to look for:
+- Whether `WINWORD.EXE` was already running when the job started, and whether it stayed open through the export.
+- Run surface: Studio Run/Debug foreground vs attended vs unattended/Session 0 vs background.
+- Scope structure: is the export the child of the scope that opened the document; any `Parallel`/`Pick`/`Invoke`/coded thread between scope-open and export.
+- `UiPath.Word.Activities` version (stable vs alpha/pre-release).
+
+## Investigation
+
+1. Read the error from job evidence. Confirm the HRESULT is `0x8001010E RPC_E_WRONG_THREAD` and the IID is `{0002096B-...}` (`_Document`). Distinguish from `0x80010108 RPC_E_DISCONNECTED` (server died) — different cause, different fix.
+2. Read the faulted activity and its surrounding `Word Application Scope` / `Use Word File` from the `.xaml`. Confirm the export is correctly nested (sole/last child of the scope that opened the document) and capture the scope's `FilePath` / `CreateNewFile`.
+3. Trace threading from source: grep the workflow(s) for `Parallel`, `ParallelForEach`, `Pick`, `PickBranch`, `InvokeWorkflowFile`, `InvokeCode`, and coded `.cs` workflows. If any sits between scope-open and export, the off-STA cause is in play.
+4. Establish the runtime sequence (ask the user if not in logs): Was Word already open when the run started? Did that Word window close before the export ran? Was the run foreground Studio / attended, or unattended / Session 0 / background?
+5. Grep the workflow for any activity that closes or kills Word or a host app (`Close Application`, `Close Window`, `Kill Process`, `Quit`, host `Dispose`). If none exist, a mid-run close was external/manual — out of the workflow graph.
+6. Read `UiPath.Word.Activities` version from `project.json`. Note whether it is a pre-release / alpha build vs the stable version bundled with the runtime's LTS.
+
+## Resolution
+
+- **If Word was already open / attached externally (and/or closed mid-run):** ensure no user-opened `WINWORD.EXE` is running when the workflow executes, and do not open or close Word on the host during the run — let the scope own its own Word instance. Confirm with an A/B re-run: Trial A opens external Word, lets the scope attach, then closes that Word window before the export (expect the error); Trial B runs with no external Word open (expect success). Error only in A confirms the attachment / mid-run-close cause.
+- **If the export must run while Word may be open, or unattended:** migrate the document-to-PDF path to the **System Word** activities (background, no Word UI, no shared interop instance), which remove the dependency on an interactive/external Word. Verify the System Word group covers the export before migrating; if it does not, keep `Word Application Scope` and apply the no-external-Word fix above.
+- **If the run surface is unattended / Session 0 / background:** Word interop requires an interactive STA session. Run the automation attended in an interactive session, or switch to the System Word (background) activities. If a `Parallel`/`Pick`/`Invoke`/coded thread sits between scope-open and export, move the export onto the same thread/scope that opened the document.
+- **If the package is a pre-release / alpha build:** pin `UiPath.Word.Activities` to the stable version bundled with the runtime's LTS and re-test to rule out a build regression.
+
+If the failure persists after no external Word is present and the run is attended/STA, capture a `Verbose` robot log plus the full marshalling stack trace and open a UiPath support case — the residual cases are package or Office-version-specific bugs that need vendor diagnosis.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-open-sharepoint-url-com-command-failed.md

@@ -0,0 +1,45 @@
+---
+confidence: medium
+---
+
+# Word Application Scope — Open SharePoint URL COMException "Command failed"
+
+## Context
+
+What this looks like:
+- `Word Application Scope` / `Use Word File` faults on **open**, not on a child save/export.
+- Exception type `System.Runtime.InteropServices.COMException`, message `Command failed`.
+- Stack runs through the OPEN path:
+  - `Microsoft.Office.Interop.Word.Documents.Open(...)`
+  - `UiPath.Word.Windows.Utilities.WordDocumentFactory.OpenOrCreateNewDocument`
+  - `UiPath.Word.Windows.Utilities.WordDocumentFactory.CreateDocument` / `CreateRuntimeWordDocument`
+  - `UiPath.Word.Activities.WordApplicationScope.Execute`
+- The scope's `FilePath` is a SharePoint / OneDrive **web sharing link**, recognizable by a `:w:` / `:x:` / `:p:` / `:f:` segment and a `?e=` token — e.g. `https://<tenant>-my.sharepoint.com/:w:/p/<user>/<token>?e=<id>`. The scope is often nested inside a `Use OneDrive and SharePoint` (`UseDriveCard`) activity.
+- Distinct from the COM wrong-thread cast (`0x8001010E`, IID `{0002096B-...}`) — that faults on a child cast, not on `Documents.Open`. See [word-export-pdf-com-wrong-thread.md](./word-export-pdf-com-wrong-thread.md).
+
+What can cause it (more than one may apply):
+- **Web-view sharing-link URL passed verbatim** — `Word Application Scope` passes `FilePath` straight to local Word's `Documents.Open`. A `:w:`/`:f:` sharing link is a browser-redirect landing page, not a document filename, so `Documents.Open` cannot resolve it → generic `COMException "Command failed"`. The enclosing `Use OneDrive and SharePoint` card does **not** pre-download or resolve the file for the nested Word activity — it only manages the M365 connection.
+- **`CreateNewFile` against a URL** — `CreateNewFile` defaults `True` when the attribute is absent. "Create if not exists" is not supported with a URL path; `uip rpa validate` surfaces this as a warning, and the create branch fails against a remote URL.
+- **File not openable by Word** — locked / checked-out, Protected View, password-protected, an online-only OneDrive placeholder not materialized locally, or an unsupported format.
+
+What to look for:
+- The exact `FilePath` value and whether it is a `:w:`/`:f:` sharing link vs a direct document URL vs a local/UNC path.
+- Whether `CreateNewFile` is set or defaulting to `True`.
+- Whether the document already exists at the target location.
+
+## Investigation
+
+1. Read the error from job evidence. Confirm the type is `COMException` with message `Command failed` and the top frame is `Documents.Open` (the OPEN branch) — not a child cast and not `WordAppHelpers.StartNewApplication` (COM-start; see [word-com-start-background-session0.md](./word-com-start-background-session0.md)).
+2. Read the faulted `Word Application Scope` from the `.xaml`. Capture the verbatim `FilePath`, the `CreateNewFile` value (absent ⇒ `True`), and whether the scope sits inside a `Use OneDrive and SharePoint` / `UseDriveCard`.
+3. Classify the `FilePath`: a SharePoint web-view **sharing link** has a `:w:`/`:x:`/`:p:`/`:f:` segment and a `?e=` token. A **direct document URL** looks like `https://<tenant>-my.sharepoint.com/personal/<user>/Documents/<file>.docx`. A **local/synced** path is a drive/UNC path.
+4. Run `uip rpa validate --file-path "<MAIN_XAML>" --output json`. A warning `'Create if not exists' is not supported when using a URL for the file path` confirms the `CreateNewFile`-with-URL problem.
+5. Out-of-band: have the user paste the `FilePath` into desktop Word **File > Open** on the robot host. A sharing link fails there too; a direct document URL or synced local path opens.
+
+## Resolution
+
+- **If `FilePath` is a `:w:`/`:f:` sharing link:** replace it with a Word-openable form — a direct document URL (`.../personal/<user>/Documents/<file>.docx`; in SharePoint use *Copy link* and pick a direct document link, strip any `?web=1`/`?e=` suffix), a WebDAV-style path, or a synced/downloaded local path. Confirm the replacement opens in desktop Word File > Open before relying on it.
+- **If `CreateNewFile` defaults `True` and the document already exists:** set `CreateNewFile = False`. "Create if not exists" is unsupported with a URL path; re-run `uip rpa validate` and confirm the warning clears.
+- **If the document must stay in SharePoint:** restructure to **download-then-open** — the `Use OneDrive and SharePoint` card does not auto-download for the nested Word activity, so use the connector's file activities to pull the file to a local path, then point `Word Application Scope` at that local path. A guaranteed-local path removes the URL-format and authentication dependencies entirely.
+- **If a direct URL still fails after the format is correct:** local Word reaching SharePoint depends on cached M365 credentials in the robot's Word process; an unauthenticated open surfaces the same generic `COMException`. Prefer a synced/local path, or ensure the robot's Word session is signed in to the tenant.
+
+If the failure persists with a confirmed Word-openable path that opens in desktop Word File > Open, capture a `Verbose` robot log plus the full stack and open a UiPath support case.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-scope-cannot-create-unknown-type.md

@@ -0,0 +1,30 @@
+---
+confidence: high
+---
+
+# Word Application Scope — "Cannot create unknown type WordApplicationScope"
+
+## Context
+
+What this looks like:
+- The workflow fails to load or compile with `Cannot create unknown type '{clr-namespace:UiPath.Word.Activities;assembly=UiPath.Word.Activities}WordApplicationScope'` (or a similar "unknown type" / "could not load activity" error)
+- The failure happens before any document is touched — at job start or during package restore, not at runtime inside the scope
+
+What can cause it:
+- The machine executing the job **lacks the `UiPath.Word.Activities` package dependency**, or has a version that does not contain the `WordApplicationScope` type. The XAML references the activity, but the assembly is not restored on that host.
+- **Version mismatch across environments** — the package resolves locally in Studio but a different (or missing) version is installed on the remote/unattended robot via Orchestrator, so the type cannot be created there.
+
+What to look for:
+- `project.json` lists `UiPath.Word.Activities` but the robot's package cache / feed does not have that version.
+- Works in Studio, fails only when run via Orchestrator on a remote robot.
+
+## Investigation
+
+1. Open `Manage Packages` in Studio and confirm `UiPath.Word.Activities` is installed and referenced. Compare the resolved version against `project.json`.
+2. If the job runs via Orchestrator on a remote robot, confirm the same `UiPath.Word.Activities` version is available on that robot — check the robot's package feed and that the published package bundled the dependency.
+
+## Resolution
+
+- **If the package is missing or out of date in Studio** — install / update `UiPath.Word.Activities` via `Manage Packages`, rebuild, and re-publish.
+- **If the version differs across environments** — pin the dependency version in `project.json` and confirm that exact version is published to the feed the robot restores from, so versions match perfectly across Studio and every robot.
+- **If running on a remote robot** — confirm the robot can reach the package feed and that the published process bundled `UiPath.Word.Activities`; republish if the dependency was not included.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-scope-com-not-installed.md

@@ -0,0 +1,35 @@
+---
+confidence: high
+---
+
+# Word Application Scope — Error Opening Document / Word Not Installed (COM Interop)
+
+## Context
+
+What this looks like:
+- Activity `Word Application Scope` (`UiPath.Word.Activities.WordApplicationScope`) faults the moment it tries to open the document, before reading or writing any content
+- Error message contains one of: `Error opening document, make sure Word application is installed`, `Could not load file or assembly 'Microsoft.Office.Interop.Word'`, `Retrieving the COM class factory for component with CLSID {000209FF-0000-0000-C000-000000000046} failed`, `80040154 (REGDB_E_CLASSNOTREG)`, or `Cannot create an instance of Microsoft.Office.Interop.Word.ApplicationClass`
+
+What can cause it:
+- `Word Application Scope` drives the **Microsoft Word Interop API** — it launches a real WINWORD.EXE via COM. The scope cannot establish that COM connection when:
+  - Desktop Word is not installed on the execution host (only the web/online version is available, a Linux robot, a stripped-down VM, or a container image)
+  - A **bitness conflict** between Office and the robot process — 32-bit Office against a 64-bit robot (or vice versa) — so cross-bitness COM marshaling fails to create the class factory
+  - Office is installed but its COM registration is damaged (failed update, partial install)
+
+What to look for:
+- `REGDB_E_CLASSNOTREG` / `make sure Word application is installed` is the signature of "no usable desktop Word for Interop" — it is an environment fault, not a workflow defect.
+
+## Investigation
+
+1. Read the faulted node from the workflow `.xaml` and confirm it is `Word Application Scope` (classic Interop) rather than the modern `Use Word File` surface.
+2. Confirm desktop Microsoft Word is installed on the execution machine. Ask the user (or someone with access to the robot host, signed in as the robot's Windows user) to check `Control Panel > Programs and Features` for a Microsoft Office / Microsoft 365 entry, or run `Get-ItemProperty 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\winword.exe'` in PowerShell. Web/online Word does not satisfy Interop.
+3. Capture the Office bitness (`File > Account > About Word`) and compare it against the robot process bitness. A 32-bit/64-bit mismatch is a common cause when Word *is* installed but the scope still faults at startup.
+4. Confirm the robot type. Linux robots and many cloud/container unattended hosts have no Word and cannot run Interop activities at all.
+
+## Resolution
+
+- **If Word is not installed** — install the desktop Microsoft Word (or full Office / Microsoft 365 desktop suite) on the execution machine under a license the robot's Windows user can activate, then re-run.
+- **If only web/online Office is present** — the online edition cannot back Interop. Install the desktop suite, or migrate the workflow to the modern `Use Word File` surface where the operation supports it.
+- **If Office and robot bitness differ** — reinstall Office at the same bitness as the robot (preferred: 64-bit Office for 64-bit robots), or run the robot under the matching bitness.
+- **If Office is installed at matching bitness but COM is still unregistered** — run the Office Repair tool: `Control Panel > Programs and Features > Microsoft Office > Change > Repair` (Online Repair re-registers the COM components).
+- **If Word cannot be installed on the host** (Linux robot, locked-down VM, container) — re-architect to avoid Interop. There is no in-place workaround; `Word Application Scope` requires a registered desktop Word.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-scope-file-corrupted.md

@@ -0,0 +1,34 @@
+---
+confidence: medium
+---
+
+# Word Application Scope — "The file appears to be corrupted"
+
+## Context
+
+What this looks like:
+- Activity `Word Application Scope` (`UiPath.Word.Activities.WordApplicationScope`) faults opening or saving the document with a message containing `The file appears to be corrupted`, `Word experienced an error trying to open the file`, or `cannot be opened because there are problems with the contents`
+- The same document opens cleanly when a user double-clicks it interactively — corruption is intermittent / robot-only
+
+What can cause it (more than one may apply):
+- **Background WINWORD.EXE holds a lock** — a previous run (or a crashed scope) left an orphaned WINWORD.EXE owning the file handle, so the new run cannot read/save and Word reports the half-written file as corrupted
+- **Template reused in place** — the workflow opens a template `.docx`/`.dotx`, edits it, and writes back to the same path. A concurrent/locked handle leaves the source partially overwritten and unreadable on the next open
+- **Mark-of-the-Web / Protected View** — the file came from the internet or an untrusted share; Word opens it in Protected View and the Interop write fails, surfacing as a content/corruption error
+
+What to look for:
+- Multiple `WINWORD.EXE` instances in Task Manager on the robot host with no visible window.
+- Whether the input path and the output path are the **same file** (in-place template overwrite).
+
+## Investigation
+
+1. Read the `Word Application Scope` node from the `.xaml`. Capture the input document path and the path the workflow saves to. Note whether they are identical (in-place edit of a template).
+2. Check the robot machine for orphaned `WINWORD.EXE` processes before the next run (Task Manager → instances with no window).
+3. Ask the user to open the failing document interactively on the robot host as the robot's Windows user. If it opens in **Protected View** (yellow banner) or prompts for recovery, that is the blocking state.
+4. Confirm the file is not held open by a sync client (OneDrive/SharePoint), antivirus, or a concurrent job at failure time.
+
+## Resolution
+
+- **If an orphaned WINWORD.EXE holds the file** — add a `Kill Process` activity configured for `WINWORD` immediately **before** the `Word Application Scope` to clear locked sessions. As a one-time cleanup, end stray instances via Task Manager or `Stop-Process -Name WINWORD -Force`. Going forward, ensure the scope always disposes (no `Try/Catch` swallowing its exit) so it closes Word cleanly.
+- **If the workflow overwrites a template in place** — change the workflow to **save as a new file** (a distinct output path), leaving the source template untouched. Build the output path with `Path.Combine` rather than reusing the input path variable.
+- **If the document opens in Protected View / Mark-of-the-Web** — unblock the file (`Right-click > Properties > Unblock`) or pre-process it with `Unblock-File <path>` in PowerShell before the workflow runs; or add the folder to Word Trusted Locations (`File > Options > Trust Center > Trust Center Settings > Trusted Locations`).
+- **If the source file is genuinely corrupt** — open it interactively, use `File > Open > Open and Repair`, save a clean copy, and point the workflow at the repaired file.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-scope-file-path-not-found.md

@@ -0,0 +1,36 @@
+---
+confidence: medium
+---
+
+# Word Application Scope — File Path Verification Errors / Document Not Found
+
+## Context
+
+What this looks like:
+- Activity `Word Application Scope` (`UiPath.Word.Activities.WordApplicationScope`) faults because the target document does not exist at the resolved path — `Could not find file '<path>'`, `Could not find a part of the path`, or a generic open failure pointing at a path that is wrong
+- The path string is built dynamically and resolves to the wrong location at runtime
+
+What can cause it:
+- The target file genuinely does not exist (the workflow expects to **create** a new document but the scope is configured to open an existing one)
+- A **relative path** resolves against the wrong working directory — on an unattended robot a relative path resolves against the robot's working directory (often `C:\Windows\System32\config\systemprofile`), not the project folder, so a path that resolves correctly in Studio is not found at runtime
+- A **dynamically generated path** is built incorrectly (string concatenation with wrong separators, missing folder segment, stale variable)
+- Under an unattended robot session, a mapped drive letter is not available, or a OneDrive/SharePoint Files-On-Demand placeholder has not been hydrated
+
+What to look for:
+- Whether the workflow intends to open an existing document or create a new one.
+- How the path is constructed (literal vs. concatenation vs. `Path.Combine`).
+
+## Investigation
+
+1. Read the `Word Application Scope` node from the `.xaml` and capture the literal expression bound to the document path.
+2. Resolve that expression to a concrete path for the failing run and confirm whether the file exists at that location on the robot host (not the developer machine).
+3. If the path is relative, determine the robot's working directory at run time — relative paths resolve there, not against the document's folder.
+4. Confirm the intent: is the scope meant to open an existing document, or generate a new one?
+
+## Resolution
+
+- **If a new document should be created** — enable the activity's `Create if not exists` option so the scope generates the file when it is absent, instead of faulting.
+- **If the path is relative or fragile** — build an **explicit absolute path** (an absolute root or a UNC path the robot can reach), or anchor the filename to a known base folder, rather than concatenating bare strings — so it resolves deterministically on every host. Do **not** rely on `Environment.CurrentDirectory`: on an unattended robot that is the robot's working directory (`...\systemprofile`), not the project folder, so `Path.Combine(Environment.CurrentDirectory, "yourfile.docx")` resolves to the same wrong location that failed. For a configurable base, store the folder path in an Orchestrator asset and combine the filename onto it.
+- **If a mapped drive / cloud placeholder is the issue** — use a UNC path the robot session can reach, or ensure OneDrive/SharePoint files are hydrated (not Files-On-Demand placeholders) before the run.
+- **If the file was moved/deleted upstream** — fix the upstream step that produces it, or add a `Path Exists` check before the scope to fail with a clear message instead of a raw open error.
+- **If you are on StudioX / modern design** — consider replacing `Word Application Scope` with the modern `Use Word File` activity, which provides improved stability and clearer file-resolution behavior.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/word-scope-hangs-background-prompt.md

@@ -0,0 +1,34 @@
+---
+confidence: medium
+---
+
+# Word Application Scope — Workflow Hangs / Freezes on a Background Dialog
+
+## Context
+
+What this looks like:
+- The job reaches the `Word Application Scope` (`UiPath.Word.Activities.WordApplicationScope`) and then hangs indefinitely — no error, no progress, until the job times out
+- WINWORD.EXE is running but unresponsive to the robot's COM calls
+
+What can cause it:
+- Word opened a **modal prompt in the background** that requires user interaction and blocks all COM calls until dismissed. Common prompts: a "Password Protected" / "Enter password" dialog, a document-recovery sidebar, a "Safe Mode" message after a prior crash, an activation/license prompt, or a "trust this file" / Protected View bar
+- When the scope runs unattended (no visible Word window), the dialog is invisible to anyone watching the robot but still wedges the process
+
+What to look for:
+- One or more hidden `WINWORD.EXE` instances stuck in Task Manager during the freeze.
+- Whether the document is password-protected, was recovered from a prior crash, or last closed uncleanly.
+
+## Investigation
+
+1. Reproduce with Word **visible**: ask the user (or someone with desktop access on the robot host, signed in as the robot's Windows user) to run the workflow and watch WINWORD.EXE. Note any dialog, banner, recovery sidebar, or Safe Mode prompt that appears.
+2. Open the target document manually once on the robot host to surface and clear any startup alert (recovery pane, activation, trust prompt).
+3. During the freeze, open Task Manager and check for multiple hidden `WINWORD.EXE` processes stuck with no window.
+4. Confirm whether the document is password-protected and whether the scope supplies the password.
+
+## Resolution
+
+- **If a recovery sidebar / Safe Mode prompt appears** — open the document interactively on the robot host, dismiss the recovery/Safe Mode prompt, then save and close cleanly so the startup state is cleared before the next run.
+- **If a password prompt blocks it** — supply the password in the `Word Application Scope` properties, or remove protection from the source document if it does not need to be encrypted.
+- **If an activation / "trust this file" prompt blocks it** — complete Office activation under the robot's Windows user, and add the document folder to Word Trusted Locations (`File > Options > Trust Center > Trust Center Settings > Trusted Locations`).
+- **If WINWORD.EXE was left orphaned and wedged** — add a `Kill Process` for `WINWORD` before the scope, and ensure the scope disposes on every path so Word always closes cleanly.
+- **As a guard against silent hangs** — wrap the scope so the job fails fast rather than hanging forever (set a finite timeout on the surrounding sequence / job), and prefer the modern `Use Word File` surface where it avoids the interactive-prompt failure mode.

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

@@ -0,0 +1,11 @@
+# Word Activities Presentation Rules
+
+- **Activities** — use the display name (e.g., "Word Application Scope", "Use Word File", "Kill Process"), not the fully qualified class name (e.g., `UiPath.Word.Activities.WordApplicationScope`)
+- **Documents** — refer to documents by their filename (e.g., "document 'Contract.docx'") or full path when ambiguous; not by the variable holding the document reference
+- **Office versions** — refer to Office by its installed product name and bitness (e.g., "Microsoft 365 Apps for Enterprise (64-bit)", "Office 2019 (32-bit)"), not by internal version numbers like `16.0` unless they are the only identifier available
+- **Word settings** — refer to Trust Center settings by the exact UI label path the user navigates (e.g., `File > Options > Trust Center > Trust Center Settings > Trusted Locations`), so the user can find the toggle without guessing
+- **Processes** — refer to the Word process as `WINWORD.EXE` (the executable name the user sees in Task Manager), not "Word process" alone
+- **Replace Text** — refer to the activity by display name ("Replace Text in Document" / classic "Replace Text"), and to its inputs by the property labels the user sees (`Search` / "Search for", `Replace` / "Replace with"); quote placeholder tokens exactly as they appear in the template (e.g. "`[Name]`")
+- **Word instances** — refer to the external Word process as "Microsoft Word (`WINWORD.EXE`)" so the user knows which process to check for or close
+- **HRESULTs** — quote the exact code and symbol together (e.g. "`0x8001010E RPC_E_WRONG_THREAD`"), and name the IID's interface (`{0002096B-...}` = `Microsoft.Office.Interop.Word._Document`) so the user can correlate it with the stack trace
+- **Run surface** — name the surface in the user's terms (e.g. "Studio Run/Debug (foreground)", "unattended robot (Session 0)"), not internal runtime flags like `isAttended`

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

@@ -0,0 +1,38 @@
+# Word Activities Playbooks
+
+**Overview:** [overview.md](./overview.md) — `UiPath.Word.Activities` package, execution models, and common failure patterns
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Word Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Word COM / Office Interop Failures & Word Process Crashes | Medium | Environmental/host-level COM failures common to **all** Word activities (the scope and any COM-driven activity), not just `Add Picture`: (E1) type library / class not registered (`0x8002801D` / `0x80040154`); (E2) 32/64-bit mismatch between Studio/Robot and Office; (E3) Word busy or blocked (`0x8001010A` / `0x80010001`) from orphaned `WINWORD.EXE` or a modal/Protected-View dialog; (E4) `WINWORD.EXE` crashes mid-operation and the activity then throws `RPC_E_WRONG_THREAD` (`0x8001010E`) on its async-completion path (a known `Add Picture` trigger: inserting a very large image, which the activity cannot resize) | [word-com-interop-failures.md](./playbooks/word-com-interop-failures.md) |
+| Word Application Scope — Error Opening Document / Word Not Installed | High | COM Interop cannot create the `Word.Application` instance — no desktop Word (web-only Office, Linux/container robot), 32-bit/64-bit Office–robot bitness mismatch, or damaged Office COM registration (`make sure Word application is installed`, `REGDB_E_CLASSNOTREG`) | [word-scope-com-not-installed.md](./playbooks/word-scope-com-not-installed.md) |
+| COM Start Fails in Background / Session 0 | Medium | `Word Application Scope` faults on **COM start** (`WordAppHelpers.StartNewApplication` → `ComAppReferenceCountManager.StartOrAttach`) with `UiPath.Word.WordException: "Error opening document, make sure Word application is installed. If already installed, an Office Repair may be required."` on an unattended robot. Primary cause: process published as a Background Process (`runtimeOptions.requiresUserInteraction: false`) runs in Session 0 with no interactive session, so Office COM can't start — Word opens fine interactively but the headless robot fails. Fix: publish foreground / open an interactive session / Use Foreground (NOT Office Repair). Also covers Word-not-installed and broken-registration | [word-com-start-background-session0.md](./playbooks/word-com-start-background-session0.md) |
+| Word Application Scope — "The file appears to be corrupted" | Medium | Opening/saving reports corruption — orphaned WINWORD.EXE holding the lock, in-place template overwrite leaving a half-written source, or Protected View / Mark-of-the-Web blocking the write | [word-scope-file-corrupted.md](./playbooks/word-scope-file-corrupted.md) |
+| Word Application Scope — Workflow Hangs / Freezes Indefinitely | Medium | WINWORD.EXE is up but unresponsive because Word opened a background modal prompt (password, document-recovery sidebar, Safe Mode, activation, trust-this-file) that blocks COM calls; invisible when the scope runs unattended | [word-scope-hangs-background-prompt.md](./playbooks/word-scope-hangs-background-prompt.md) |
+| Word Application Scope — "Cannot create unknown type WordApplicationScope" | High | Load/compile-time failure: the execution host lacks the `UiPath.Word.Activities` dependency or runs a version without the type; common when a process works in Studio but fails on a remote robot with a different/missing package version | [word-scope-cannot-create-unknown-type.md](./playbooks/word-scope-cannot-create-unknown-type.md) |
+| Word Application Scope — File Path Verification Errors / Document Not Found | Medium | The document path does not resolve at runtime — opening a file that should be created (`Create if not exists` unset), a relative path resolved against the wrong working directory, a malformed dynamic path, or an unavailable mapped drive / unhydrated cloud placeholder | [word-scope-file-path-not-found.md](./playbooks/word-scope-file-path-not-found.md) |
+| Replace Text in Document — "Application is busy" / COM Interop (0x8001010A) | Medium | The activity's COM call is rejected because WINWORD.EXE is busy — open in the background, locked by another session, or stalled on a hidden modal dialog (`RPC_E_SERVERCALL_RETRYLATER`, `RPC_E_CALL_REJECTED`) | [replace-text-com-busy.md](./playbooks/replace-text-com-busy.md) |
+| Replace Text in Document — File Lock / "File is Read-Only" on Save | Medium | The scope cannot persist the edit because the file is in use or read-only — `Auto Save` racing another access in a loop, a `Save As`/rename to the same open path, a concurrent job, or the read-only attribute set | [replace-text-file-locked.md](./playbooks/replace-text-file-locked.md) |
+| Replace Text in Document — Placeholder Not Replaced (No Error, No Change) | Medium | Silent miss: the placeholder is split across Word XML runs (edited/reformatted in place) so the exact-string search never matches; the activity succeeds but the document is unchanged | [replace-text-silent-no-substitution.md](./playbooks/replace-text-silent-no-substitution.md) |
+| Replace Text in Document — Input String Length Limit (256 chars) | High | Classic versions cap `Search`/`Replace` at 256 characters; longer values raise `ArgumentException` or truncate silently. Fix: upgrade the package or substitute via string/regex in code | [replace-text-length-limit.md](./playbooks/replace-text-length-limit.md) |
+| Replace Text in Document — TargetInvocationException / Studio Crash on Drop | Medium | Design-time crash when the activity is dropped or the workflow opened — a Studio↔`UiPath.Word.Activities` version mismatch fails to construct the designer (`TargetInvocationException`). Distinct from the runtime "Cannot create unknown type" fault | [replace-text-version-mismatch.md](./playbooks/replace-text-version-mismatch.md) |
+| Replace Text in Document — Placeholder Replaced Once, Then Missing in Loop | Medium | Works on the first loop iteration, then the placeholder is gone on later rows — the workflow edits the template in place, so the first replacement consumes the placeholder. Fix: Copy File to a fresh temp template per iteration | [replace-text-loop-template-overwrite.md](./playbooks/replace-text-loop-template-overwrite.md) |
+| Replace Text in Document — Headers / Footers / Text Boxes Not Replaced | Medium | No error, but placeholders in headers, footers, or floating text boxes survive while body text is replaced — older `UiPath.Word.Activities` scans only the primary body. Fix: update the package (newer versions cover shapes/headers) | [replace-text-headers-textboxes-skipped.md](./playbooks/replace-text-headers-textboxes-skipped.md) |
+| Replace Text in Document — Multi-line Replacement Loses Formatting | Medium | Replacement text collapses to one line / loses formatting because the `Replace` value carries raw `Environment.NewLine` breaks. Fix: keep replacements plain, or use Bookmarks / Form Fields + Set Bookmark Text for styled multi-line content | [replace-text-multiline-formatting.md](./playbooks/replace-text-multiline-formatting.md) |
+| Read Text — Activity Outside Its Container | High | Modern Word-pack `Read Text` faults / warns as invalid when dropped outside a `Use Word File` / `Word Application Scope` (it has no file input of its own). Fix: nest it in a container, or use the standalone `System > File > Word Document` `Read Text` that takes a file path | [read-text-missing-container.md](./playbooks/read-text-missing-container.md) |
+| Read Text — Standalone System Activity Fails on .doc | Medium | The standalone `System > File > Word Document` `Read Text` is `.docx`-only and errors / returns nothing on legacy binary `.doc`. Fix: read `.doc` through a `Use Word File` (Interop reads both), or convert to `.docx` first | [read-text-doc-format.md](./playbooks/read-text-doc-format.md) |
+| Read Text — Protected View Blocks an Externally-Sourced File | Medium | Reading a file from email / internet / external share faults or hangs because Word opens it in Protected View (Mark-of-the-Web). Fix: unblock the file, add the folder to Trusted Locations, or disable Protected View on the host | [read-text-protected-view.md](./playbooks/read-text-protected-view.md) |
+| Read Text — "Application is busy" / COM Interop (0x8001010A) | Medium | WINWORD.EXE busy/locked when the read's COM call fires (`RPC_E_SERVERCALL_RETRYLATER`) — same root cause and fix as the Replace Text COM-busy case (Kill Process WINWORD before the scope / clear the lock) | [replace-text-com-busy.md](./playbooks/replace-text-com-busy.md) |
+| Export to PDF — "Command Failed" (Output Directory Missing) | Medium | `Export to PDF` / `Save Document as PDF` faults with a generic `Command Failed` because the output folder doesn't exist (the activity won't auto-create it). Fix: add a `Create Folder` before the export | [export-pdf-missing-output-dir.md](./playbooks/export-pdf-missing-output-dir.md) |
+| Export to PDF — Malformed Output Path / Missing .pdf | Medium | The output File Path is built from unformatted concatenation — no `.pdf` suffix, missing/doubled separator, or an empty variable segment — so the save fails. Fix: `Path.Combine(folder, name & ".pdf")`, validate the pieces | [export-pdf-output-path-format.md](./playbooks/export-pdf-output-path-format.md) |
+| Export to PDF — COM Interop Hang / Crash / COMException | Medium | The export hangs/crashes or throws `COMException` because an orphaned `WINWORD.EXE` or a locked input document blocks the COM call. Fix: Kill Process WINWORD before the scope, ensure the input is free; persistent → Invoke Code C# `ExportAsFixedFormat` fallback | [export-pdf-com-hang.md](./playbooks/export-pdf-com-hang.md) |
+| Export to PDF — TargetInvocationException / Outdated Package | Medium | `TargetInvocationException` / syntax bugs from an outdated `UiPath.Word.Activities` against a newer Studio — same design-time version-mismatch signature and fix (Manage Packages → update) as the Replace Text case | [replace-text-version-mismatch.md](./playbooks/replace-text-version-mismatch.md) |
+| Save Document as PDF — COM Wrong-Thread (0x8001010E) | Medium | `Save Document as PDF` (`WordExportToPdf`) or another child of `Word Application Scope` faults casting the document to `Microsoft.Office.Interop.Word._Document` (IID `{0002096B-...}`) with `RPC_E_WRONG_THREAD`. Causes: scope attached to an already-open external Word, that external Word closed mid-run, an off-STA / Session-0 / background runtime, or a non-creator thread (Parallel/Pick/Invoke/coded). `Word Application Scope` exposes no isolated-instance control | [word-export-pdf-com-wrong-thread.md](./playbooks/word-export-pdf-com-wrong-thread.md) |
+| Open SharePoint URL — COMException "Command failed" | Medium | `Word Application Scope` / `Use Word File` faults on **open** (`Documents.Open` → `WordDocumentFactory.OpenOrCreateNewDocument`) with `COMException: Command failed`. `FilePath` is a SharePoint/OneDrive web-view **sharing link** (`:w:`/`:f:` segment, `?e=` token) passed verbatim to local Word, which cannot open it. Also covers `CreateNewFile` defaulting `True` against a URL. Fix: use a direct document URL / WebDAV / synced local path, set `CreateNewFile=False`, or download-then-open | [word-open-sharepoint-url-com-command-failed.md](./playbooks/word-open-sharepoint-url-com-command-failed.md) |
+| Append Text — "Activity is valid only inside WordApplicationScope" | High | App-Integration `Append Text` faults/warns as invalid outside a `Word Application Scope` / `Use Word File` (no file input of its own). Fix: nest it in a scope, or use the standalone `Word Document` `Append Text` (takes a file path) | [append-text-missing-container.md](./playbooks/append-text-missing-container.md) |
+| Append Text — "Archive file cannot be size zero" | Medium | The target `.docx` is a 0-byte file (a renamed `.txt` or a failed/truncated write) and isn't a valid OpenXML package. Fix: delete it + check `Create if not exists`, or fix the upstream that produced the empty file | [append-text-zero-byte-file.md](./playbooks/append-text-zero-byte-file.md) |
+| Append Text — "make sure Word application is installed" | High | Same Interop/COM startup failure as Word Application Scope — no desktop Word (server/unattended). Fix: install Word, or use the standalone Word Document activities (no Word needed) | [word-scope-com-not-installed.md](./playbooks/word-scope-com-not-installed.md) |
+| Append Text — File Lock / Corrupted File | Medium | The target document is open/locked by a user or an orphaned WINWORD.EXE, blocking write — same lock family as the Word Application Scope corrupted-file case (Kill Process winword before the scope) | [word-scope-file-corrupted.md](./playbooks/word-scope-file-corrupted.md) |
+| Append Text — Missing / Unresolved Activity (Package) | Medium | The activity shows missing/invalid (esp. after migration) — same `UiPath.Word.Activities` package-version issue as the Replace Text version-mismatch case (Manage Packages → update / reinstall) | [replace-text-version-mismatch.md](./playbooks/replace-text-version-mismatch.md) |
+| Add Picture (WordAddImage) Failures | Medium | `Add Picture` fails to insert an image. Four categories: (C1) activity placed outside a `Use Word File` / `Word Application Scope`; (C2) Word COM interop exception or Word process crash — environmental/host, see [word-com-interop-failures.md](./playbooks/word-com-interop-failures.md); (C3) insertion target (text/bookmark) not found in the open document; (C4) invalid path or an in-memory `UiPath.Core.Image` bound to `Picture to insert` instead of a path string | [add-picture-failures.md](./playbooks/add-picture-failures.md) |

package/skills/uipath-troubleshoot/references/products/integration-service/investigation_guide.md

@@ -30,6 +30,15 @@ If no source code is available, the error message usually names the connection.
 
 If the connection identity is still unclear, ask the user which connection or connector is involved.
 
+## Connector Activity Runtime Exceptions
+
+When the failure is a robot exception thrown by a connector activity (`ConnectorActivity`, `ConnectorTriggerActivity`, `ConnectorHttpActivity`, `ConnectorPersistenceActivity`), the exception class and its error code route the diagnosis:
+
+- **`GeneralException` / `RuntimeException`** carry a structured `DAP-` code (`DAP-GE-####`, `DAP-RT-####`). The code maps to an exact cause — read it from the job log / Info and match the corresponding playbook before gathering more data. `DAP-GE-*` = connection resolution; `DAP-RT-*` = binding / input / trigger / operation.
+- **`UiPath.Ipc.RemoteException` / `UiPath.CoreIpc.RemoteException`** carry NO DAP code. They are a generic out-of-process wrapper — **unwrap to the innermost message** (follow `--->` chains) and classify on that (token/auth, transport, downstream HTTP). The `RemoteException` class itself is not IS-specific; only treat it as a connector failure when the faulted activity is a connector activity and the inner message fits.
+- **`System.AggregateException`** is never the cause — unwrap `InnerExceptions[0]` (recurse) and re-classify on the inner exception.
+- **`System.NullReferenceException`** has no detail — use the stack frame (often a `ForEach` over a `SWEntities.*_List` connector output) to find which reference was null.
+
 ## Domain-Specific Data Gathering
 
 After the Orchestrator job data bundle (job details, logs, traces) is collected and the connection is identified:

package/skills/uipath-troubleshoot/references/products/integration-service/overview.md

@@ -32,6 +32,13 @@ Organization (cloud.uipath.com)
 - **Triggers** — event-based subscriptions that can start Orchestrator jobs or Maestro instances
 - **OAuth Management** — create, re-authenticate, and ping connections via OAuth flows
 
+## Runtime Execution Model
+
+Connector activities (`ConnectorActivity`, `ConnectorTriggerActivity`, `ConnectorHttpActivity`, `ConnectorPersistenceActivity`) execute **out-of-process** in the connector executor and communicate over IPC. Two consequences for diagnosis:
+
+- The runtime wraps failures in its own exceptions with structured codes — `GeneralException` (`DAP-GE-*`, connection resolution) and `RuntimeException` (`DAP-RT-*`, binding/input/operation).
+- An unhandled fault in the executor process crosses the IPC boundary as `UiPath.Ipc.RemoteException` / `UiPath.CoreIpc.RemoteException` (no DAP code) — the real error is the inner message.
+
 ## Connection Resource File
 
 Projects and solutions store connection references as JSON files. The location depends on whether the project is standalone or part of a solution — **always check both layouts**:

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connection-invalid.md

@@ -44,6 +44,15 @@ What to look for:
 
 4. **Cross-reference workflow binding** — if the workflow source is available, confirm the connection ID in the activity (`ConnectionId`/`ConnectionKey` attributes in XAML, or equivalent in coded workflows) matches `resource.key` from step 1. A mismatch means the runtime error connection ID is hard-bound elsewhere.
 
+5. **Disambiguate the 404 — "deleted" vs "cross-workspace."** A `ping` 404 means the connection is *not resolvable from the runner's context*, NOT necessarily *deleted*. Decide using the step-1 resource-file evidence, not the 404 alone:
+
+   | `ping` result | resource file `resource.name` / `resource.folders` | Cause |
+   |---------------|-----------------------------------------------------|-------|
+   | 404 | runner's own identity / job folder, OR no resource file and connection absent everywhere | Connection deleted or renamed after publish |
+   | 404 | a **different** user (email) or a workspace **other than** the runner's | Connection lives in another user's personal workspace — cross-workspace, **not** deleted |
+
+   Do NOT report "connection deleted" on a 404 alone. If the resource file's owner (`resource.name`) is a different user than the runner — e.g. the connection is owned by `original_email@…` but the job runs as `replacement_email@…` — the connection exists and is owned elsewhere: classify it as cross-workspace ownership, not deletion. Reporting the wrong mechanism (deleted vs cross-workspace) is a root-cause miss even when the recommended fix happens to coincide.
+
 ## Resolution
 
 - **If connection not found in folder:** tell the user to create a new connection using the exact `connectorName` from step 1 (e.g., "Create a new **Microsoft OneDrive & SharePoint** connection"). If `authenticationType` is "AuthenticateAfterDeployment", tell the user they will need to authenticate the connection after creating it.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connector-aggregate-exception.md

@@ -0,0 +1,30 @@
+---
+confidence: low
+---
+
+# Connector Activity — AggregateException
+
+## Context
+
+What this looks like — robot exception `System.AggregateException` on a connector activity (the stack shows a connector class such as `UiPath.<Connector>.IntegrationService.Activities.<Operation>` or `...Scope`, often via `AsyncCodeActivity.CompleteAsyncCodeActivityWorkItem`). Connector activities run asynchronously; when the async operation faults (or several parallel branches fault), the failures are collected into an `AggregateException`. The wrapper itself carries no useful cause — **the real error is in `InnerExceptions[0]`** (and, if that is itself a wrapper, recurse).
+
+Which activities produce this:
+- **ConnectorActivity** — and connector `Scope` activities wrapping async connector calls.
+
+What can cause it:
+- Any underlying connector failure surfaced through the async boundary — most commonly a `GeneralException`/`RuntimeException` (DAP code), a `RemoteException` (token/transport/HTTP), or a downstream service error.
+- Multiple parallel connector calls where one or more faulted.
+
+## Investigation
+
+1. **Unwrap.** Read the inner exception(s) from the job log / `traces spans get` — the aggregate is never the answer. Take `InnerExceptions[0]`; if it is itself a wrapper (`RemoteException`, another `AggregateException`), recurse to the innermost concrete error.
+2. **Re-classify by the inner exception** and switch to the matching playbook:
+   - inner `...GeneralException` (DAP-GE) → [connector-general-exception.md](./connector-general-exception.md)
+   - inner `...RuntimeException` (DAP-RT) → [connector-runtime-exception.md](./connector-runtime-exception.md)
+   - inner `Ipc`/`CoreIpc` `RemoteException` → [connector-remote-exception.md](./connector-remote-exception.md)
+   - inner `NullReferenceException` → [connector-null-reference.md](./connector-null-reference.md)
+3. If multiple inner exceptions, report each — but the first concrete one is usually the root.
+
+## Resolution
+
+There is no fix for `AggregateException` itself. Resolve the **unwrapped inner exception** using the playbook it maps to (step 2). The aggregate disappears once the underlying connector failure is fixed.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connector-general-exception.md

@@ -0,0 +1,43 @@
+---
+confidence: high
+---
+
+# Connector Activity — GeneralException (DAP-GE)
+
+## Context
+
+What this looks like — robot exception `UiPath.IntegrationService.Activities.Runtime.Exceptions.GeneralException` with a `DAP-GE-` error code. The job faults at the moment the connector activity tries to resolve its connection (before the external API is called). The message carries the code:
+
+- `Failed to retrieve connection. Consider using a different connection. Error code: DAP-GE-3000.` — and a `-`-delimited detail that names the real cause:
+  - `- Connection [<id>] is invalid or you do not have access to it` — connection missing, deleted, or not accessible from the runner's identity/workspace.
+  - `- User '<user-id>' does not have Connections.View permissions in [Connection: <id>]` — RBAC: the runner (robot account in deployed mode) lacks `Connections.View` in the folder where the connection lives.
+  - `- Bad Gateway` (or other upstream text) — Integration Service / Identity returned a 5xx while resolving the connection.
+- `Connection is disabled. Please enable the connection to continue. Error code: DAP-GE-3005.` — the connection exists and is bound correctly but is disabled.
+
+Which activities produce this — the generic Integration Service connector activities, regardless of which connector they wrap:
+- **ConnectorActivity** — any connector operation (per-connector classes are generated, e.g. `UiPath.Salesforce.IntegrationService.Activities.*`, but the runtime base is `ConnectorActivity`).
+- **ConnectorHttpActivity** — the connector "HTTP request" / custom-call activity.
+- **ConnectorTriggerActivity** — the trigger's debug/sample lookup resolves the same connection.
+- **ConnectorPersistenceActivity** — long-running connector waits.
+
+What can cause it:
+- **DAP-GE-3000, invalid/no-access:** connection deleted/renamed after publish; connection lives in a different user's personal workspace than the runner; folder bindings (`bindings_v2.json`) point at the wrong folder.
+- **DAP-GE-3000, Connections.View:** robot account lacks the permission in the connection's folder. Debug mode works (user identity) but deployed mode fails (robot identity).
+- **DAP-GE-3000, Bad Gateway / 5xx:** transient Integration Service / Identity outage — retryable, not a config error.
+- **DAP-GE-3005, disabled:** someone disabled the connection, or it auto-disabled after repeated auth failures.
+
+## Investigation
+
+The error code already names the cause class; the remaining work is confirming ownership/permission. Read the connection identity first.
+
+1. **Read the connection resource file** — glob `**/connection/<connector-key>/*.json` from the project root (see "Connection Resource File" in [overview.md](../overview.md)). Extract `resource.key` (connection ID — must match the ID in the error), `resource.name` (owner), `resource.folders[*].fullyQualifiedName` (binding), `spec.connectorName`. This is the only way to distinguish "deleted" from "cross-workspace ownership" for DAP-GE-3000 invalid/no-access. If no source is available, say so and proceed on the error text.
+2. For **DAP-GE-3005** the cause is unambiguous — skip to Resolution.
+3. `uip is connections ping <connection-id>` — confirms current state (disabled / not accessible).
+4. For the **Connections.View** detail: identify whether the failing identity is a robot account (deployed) vs the user (debug). Robot accounts often lack the permission the user has.
+
+## Resolution
+
+- **DAP-GE-3005 (disabled):** re-enable the connection in the Integration Service UI (or `uip is connections edit <connection-id>`). If it auto-disabled, re-authenticate — see [connection-auth-expired.md](./connection-auth-expired.md).
+- **DAP-GE-3000, invalid / no access / cross-workspace:** this is the activity-side surfacing of [connection-invalid.md](./connection-invalid.md) — follow its Resolution (create a connection in the runner's workspace and repoint the activity, or deploy to a shared folder with a shared connection).
+- **DAP-GE-3000, Connections.View:** grant the robot account at least `Connections.View` in the folder where the connection resides, **or** move/recreate the connection in a folder the robot can access (the runtime message names the connection's folder GUID and states both options verbatim).
+- **DAP-GE-3000, Bad Gateway / 5xx:** transient platform error — retry the job. If it persists, check Integration Service / Identity status before treating it as a config problem.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/connector-null-reference.md

@@ -0,0 +1,36 @@
+---
+confidence: medium
+---
+
+# Connector Activity — NullReferenceException
+
+## Context
+
+What this looks like — robot exception `System.NullReferenceException` on or just after a connector activity. There is no error code and no message detail; the stack frame is the only signal. In the telemetry it most often surfaces while **enumerating a connector output that is null** — the stack shows `UiPath.Core.Activities.ForEach`1[[...IntegrationService.Activities.SWEntities.<Cxxx>_<operation>_List...]]`, i.e. a `For Each` over a connector "List records" / query output that returned null instead of an empty list.
+
+Which activities produce this:
+- **ConnectorActivity** — and the `For Each` / downstream activity that consumes its output.
+
+What can cause it:
+- The connector operation returned **no body / null** (not an empty collection), and the workflow iterates or dereferences it without a null guard.
+- An **unmapped output argument** — the activity's result was never assigned to the variable the next activity reads.
+- A required **input object was null**, so the connector returned nothing and the workflow then dereferenced the missing output.
+- The `SWEntities` bundle type changed between publishes (regenerated connector entity), leaving a stale binding that resolves null. (If the exception is instead `InvalidCastException: Unable to cast ... SWEntities ...`, that is a distinct entity-type-mismatch failure, not this playbook.)
+
+## Investigation
+
+NRE is opaque — the goal is to find **which reference was null** and why.
+
+1. **Read the stack frame** from the job log to identify the activity and the consumed type (the `SWEntities.*_List` / `*_Get` type names the operation).
+2. If source is available, inspect the connector activity's **output mapping** and the consumer (`For Each` / `Assign`): confirm the output variable is assigned and that the consumer handles an empty/absent result.
+3. Determine whether the operation **legitimately returns nothing** for the given input (e.g. a query with no matches) — if so, the defect is the missing null/empty guard, not the connector.
+4. Check whether the project was **republished after the connector entity changed** — a stale output binding can resolve null.
+
+## Resolution
+
+- **If the operation can return no rows:** guard the output before use — check for null / empty before the `For Each` or dereference.
+- **If the output is unmapped:** assign the connector activity's result to the variable the downstream activity reads.
+- **If a required input was null:** populate it (or guard upstream) so the operation returns a result.
+- **If a stale binding after republish:** re-bind the connector activity's output to the current entity type and republish.
+
+If none of the above reproduces a null, treat as a low-confidence lead and gather more evidence (full stack, the exact activity, the input/output variables) before concluding.