@uipath/skills 1.196.0 → 1.197.0

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

@@ -0,0 +1,30 @@
+# Web Activities Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity class** — the faulted activity is the one the user is asking about. `HttpClient` (legacy) and `NetHttpRequest` (modern) both make HTTP calls but fail differently (`WebException` / `TimeoutException` vs `AggregateException`). `DeserializeJson`, `DeserializeJsonArray`, and `DeserializeXml` share the "JSON/XML string" input display name but run different parsers. Treat them as different.
+- **Exception class** — the exception type plus the faulted activity is the primary discriminator (these activities do not wrap exceptions). Read it from `JobError.Type` / the `Info` stack, not from a paraphrase.
+- **Endpoint / target** — for HTTP, the request URL in evidence is the one the user reports. A failure against a different host or path is unrelated data.
+- **Workflow file** — if the project has multiple workflows, the error originates from the workflow the user asks about, not another `.xaml` / `.cs` that uses the same activity.
+- **Timestamp** — the failure occurred in the window the user reported. Load-bearing when an endpoint had a transient outage or the payload source changed between runs.
+
+If the data doesn't match: **discard it.** Do not use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## Domain-Specific Data Gathering
+
+1. **Job logs and stack** — `uip or jobs get <job-key> --output json` → `Info` and `JobError` carry the exception class, message, faulted activity name, and `WorkflowFilePath`. `uip or jobs logs <job-key> --level Error --output json` carries the activity-level error line.
+2. **Execution traces** — `uip or jobs traces <job-key> --output json` AND `uip traces spans get --job-key <job-key> --output json`. Activity spans expose the request URL, HTTP status, and timing — they narrow whether an HTTP failure was a non-success status, a transport error, or a timeout, and whether a deserialize failure followed a prior HTTP activity in the same run.
+3. **Workflow source** — open the faulted `.xaml`/`.cs` to read how the failing input is supplied (literal vs variable, and which upstream activity produced that variable).
+
+## Testing Prerequisites
+
+Gather and verify these before drawing conclusions:
+
+1. **Activity identity** — class name and display name from the workflow source or stack trace (`HttpClient` vs `NetHttpRequest` vs which Deserialize).
+2. **Exception class + message** — verbatim, including the first stack frame. The message body (HTTP status code, `line N, position M`, parameter name) selects the cause branch.
+3. **HTTP request configuration** (HTTP activities) — `EndPoint` / `RequestUrl` value, `Method`, `TimeoutMS` / `TimeoutInMiliseconds`, `ContinueOnError`, auth type, and whether SSL verification is on. Capture from the workflow source, not a summary.
+4. **Deserialize input source** (Deserialize activities) — **the single most decisive signal.** Determine whether the `JsonString` / `XMLString` input is a literal, a workflow variable, or the `Result` / body output of an upstream `HttpClient` / `NetHttpRequest`. A malformed-payload or null-payload fault whose input comes from an upstream HTTP activity is usually a **symptom** of that HTTP call returning an error page, an empty body, or a non-success response — diagnose the HTTP call, not the parser.
+5. **`AggregateException` inner exceptions** (`NetHttpRequest`) — unwrap `InnerException` / `InnerExceptions`. The inner type (`HttpRequestException`, `TaskCanceledException`, `WebException`) is the real cause; the `AggregateException` itself is only the wrapper.
+6. **Package version** — `UiPath.Web.Activities` version. Default timeouts, retry behavior, and `ContinueOnError` defaults differ between `HttpClient` (legacy) and `NetHttpRequest` (modern) and have shifted across versions.

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

@@ -0,0 +1,36 @@
+# Web Activities
+
+Activities from the `UiPath.Web.Activities` package for HTTP calls and payload deserialization. Two families:
+
+- **HTTP request** — `HttpClient` (legacy, RestSharp-based) and `NetHttpRequest` (modern, `System.Net.Http.HttpClient` + retry/connection pipeline). Issue an outbound HTTP request and return status, headers, and body.
+- **Deserialize** — `DeserializeJson<T>` (Newtonsoft `JsonConvert.DeserializeObject`), `DeserializeJsonArray` (Newtonsoft `JArray.Parse`), `DeserializeXml` (`System.Xml.Linq.XDocument.Parse`). Parse a string into a typed object / `JArray` / `XDocument`.
+
+## Exceptions propagate raw
+
+Unlike connection-based packages (O365's `Office365Exception`, Integration Service's `GeneralException`), these activities do **NOT** wrap failures in a package-specific exception type. After tracking telemetry, the original `catch`/`rethrow` lets the raw .NET / Newtonsoft / RestSharp exception propagate to the job. So the **faulted activity class plus the exception class** — not a unique message string — is the primary discriminator. Two activities throwing `System.NullReferenceException` are different investigations.
+
+## Key activity types
+
+### HTTP request
+
+- **HTTP Client** (`HttpClient`) — legacy REST activity. `EndPoint` is `[RequiredArgument]`. Default `TimeoutMS = 6000`. On a request-build error it rethrows unless `ContinueOnError = true` (then returns an empty response). A RestSharp timeout surfaces as an explicit `System.TimeoutException`; transport/HTTP errors surface as the raw `System.Net.WebException` unwrapped from the faulted task.
+- **HTTP Request** (`NetHttpRequest`) — modern activity over `HttpClient.SendAsync` with a retry policy. Default `TimeoutInMiliseconds = 10000`, `ContinueOnError = true` (so it returns a response summary for HTTP error statuses rather than faulting). When it does fault, the async pipeline surfaces a `System.AggregateException` wrapping the real cause (`HttpRequestException`, `TaskCanceledException`, …).
+
+### Deserialize
+
+- **Deserialize JSON** (`DeserializeJson<T>`) — guards null/empty input with an explicit `ArgumentNullException`, then `JsonConvert.DeserializeObject<T>`. Malformed text → `JsonReaderException`; well-formed JSON whose shape does not fit `T` → `JsonSerializationException`.
+- **Deserialize JSON Array** (`DeserializeJsonArray`) — `JArray.Parse`. **No null guard** (contrast with `DeserializeJson`): null/unset input → `NullReferenceException`; malformed or non-array text → `JsonReaderException`.
+- **Deserialize XML** (`DeserializeXml`) — `XDocument.Parse`. Malformed XML → `System.Xml.XmlException`.
+
+## Common failure patterns
+
+- **HTTP call failed** — `HttpClient` throws `System.Net.WebException` (non-success status, DNS failure, connection refused, SSL/TLS). `NetHttpRequest` surfaces the same causes wrapped in `System.AggregateException`.
+- **HTTP timeout** — `HttpClient` throws `System.TimeoutException` when the request exceeds `TimeoutMS`. `NetHttpRequest` timeouts arrive as `AggregateException` → inner `TaskCanceledException`.
+- **HTTP null reference** — `HttpClient` throws `System.NullReferenceException` when a request input (endpoint, header, cookie, parameter) resolves to null and is dereferenced during request building.
+- **Malformed payload** — `DeserializeJson` / `DeserializeJsonArray` throw `JsonReaderException`, `DeserializeXml` throws `XmlException`, when the input string is not valid JSON/XML. Frequently a **symptom of an upstream HTTP activity** that returned an HTML error page, an empty body, or a non-JSON error envelope.
+- **Type mismatch** — `DeserializeJson` throws `JsonSerializationException` when well-formed JSON does not match the target type `T`.
+- **Null/empty payload** — `DeserializeJson` throws `ArgumentNullException` (param `JSON string`); `DeserializeJsonArray` throws `NullReferenceException` for the same null input.
+
+## Package
+
+NuGet package id: `UiPath.WebAPI.Activities` (ships the `UiPath.Web.Activities` assemblies/namespace). Studio displays it as the **Web Activities** package; the Diagnose-Agent telemetry labels it `UiPath.Web.Activities` after the namespace.

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/deserialize-malformed-input.md

@@ -0,0 +1,36 @@
+---
+confidence: high
+---
+
+# Deserialize — Malformed JSON / XML Input
+
+## Context
+
+What this looks like:
+- A deserialize activity faults parsing its input string:
+  - `DeserializeJson` (`DeserializeJson<T>`, `JsonConvert.DeserializeObject`) or `DeserializeJsonArray` (`JArray.Parse`) → `Newtonsoft.Json.JsonReaderException`, e.g. `Unexpected character encountered while parsing value: <. Path '', line 0, position 0.` or `Unexpected end of content while loading JArray. Path '', line 1, position N.`
+  - `DeserializeXml` (`XDocument.Parse`) → `System.Xml.XmlException`, e.g. `Data at the root level is invalid. Line 1, position 1.`
+- The message carries a `line`/`position` (and for JSON a `Path`) pointing at where parsing broke. The exception is raised by the parser and propagates raw.
+
+What can cause it:
+- **Input is not valid JSON/XML** — the string is HTML, plain text, an error page, a truncated/partial payload, or has a leading BOM / wrong encoding.
+- **Upstream HTTP activity returned a non-payload body** — the single most common cause: an `HttpClient` / `NetHttpRequest` whose `Result` / body is wired into this activity returned an HTML error page (`<!DOCTYPE html>...` → the classic `Unexpected character ... <`), an empty body, or a non-JSON error envelope. The deserialize fault is a **symptom** of the HTTP call, not the parser.
+- **Wrong deserializer for the data** — XML fed to a JSON activity (or vice versa), or a single JSON object fed to `DeserializeJsonArray` (which requires array `[...]` syntax).
+
+What to look for:
+- **The first offending character / `line`/`position`** — `<` at position 0 almost always means HTML where JSON was expected (an upstream error page).
+- **The source of the input string** — literal, variable, or the output of an upstream `HttpClient` / `NetHttpRequest`. Decisive: if it's an HTTP output, investigate that call.
+- **The upstream HTTP `StatusCode`** — a non-2xx status that the workflow ignored (e.g. `ContinueOnError = True`) explains a non-payload body.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `JsonReaderException` (Deserialize JSON / JSON Array) or `XmlException` (Deserialize XML); `JobError.ActivityName` names the activity.
+2. **Trace the input string to its source** in the workflow. Is `JsonString` / `XMLString` a literal, a variable, or an upstream HTTP activity's `Result` / body?
+3. **If the input is an HTTP output:** inspect that HTTP activity's `StatusCode` and body (job logs / trace spans). A non-2xx status or an HTML/empty body means the HTTP call is the real fault — pivot to the HTTP playbooks ([http-request-connection-failure.md](./http-request-connection-failure.md), [net-http-request-aggregate-failure.md](./net-http-request-aggregate-failure.md)).
+4. **If the input is a literal/variable:** validate it against the expected format; the `line`/`position` in the message localizes the defect (wrong format, truncation, encoding/BOM, or object-vs-array mismatch).
+
+## Resolution
+
+- **Upstream HTTP returned a non-payload body (most common):** fix the HTTP call so it returns the expected payload — check the endpoint/status, and do not deserialize a response without first confirming a success status. Guard the deserialize with a `StatusCode` check (and inspect the body on non-2xx).
+- **Malformed/partial/wrong-encoding payload:** correct the data at its source so it is well-formed JSON/XML; strip a leading BOM or fix the encoding if that is what the `line 0/1, position 0/1` indicates.
+- **Wrong deserializer:** use the activity that matches the data — `DeserializeXml` for XML, `DeserializeJson` for a JSON object, `DeserializeJsonArray` only for a JSON array (`[...]`).

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/deserialize-null-input.md

@@ -0,0 +1,35 @@
+---
+confidence: high
+---
+
+# Deserialize — Null / Empty Input
+
+## Context
+
+What this looks like:
+- A deserialize activity faults because its input string is null or empty. The exception type depends on the activity:
+  - **`DeserializeJson`** (`DeserializeJson<T>`) guards the input and throws `System.ArgumentNullException` with the parameter name `JSON string` — message `Value cannot be null. (Parameter 'JSON string')` (on .NET Framework: `... Parameter name: JSON string`). The guard fires on null **or** empty input.
+  - **`DeserializeJsonArray`** has **no guard** (it calls `JArray.Parse` directly), so the same null input surfaces as `System.NullReferenceException: Object reference not set to an instance of an object.`
+- The `JSON string` parameter name and the `DeserializeJson` vs `DeserializeJsonArray` activity identity together confirm this branch (vs a malformed-payload `JsonReaderException`, where a non-null but invalid string parsed and failed).
+
+What can cause it:
+- **Unassigned / null input variable** — the `JsonString` argument is wired to a variable that is `Nothing` (never assigned, or assigned only on a path not taken) at runtime.
+- **Empty input** (`DeserializeJson` only) — the variable is `""`; the guard treats empty the same as null.
+- **Null upstream value** — the input came from a prior activity that returned nothing: an HTTP call whose body was empty / never set, an asset/config read that returned null, or a no-match lookup.
+
+What to look for:
+- **The parameter name `JSON string`** in an `ArgumentNullException` → confirms `DeserializeJson` received null/empty.
+- **A bare `NullReferenceException` on `DeserializeJsonArray`** → same root cause (null input) without the friendly guard.
+- **The source of `JsonString`** — which variable, and where it is assigned; the upstream activity that should have produced it.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info`. `ArgumentNullException (Parameter 'JSON string')` on `DeserializeJson`, or `NullReferenceException` on `DeserializeJsonArray`; `JobError.ActivityName` names the activity.
+2. **Trace `JsonString` to its assignment** in the workflow source. Identify the variable and every place it is (or is not) set on the failing path.
+3. **Check the upstream producer.** If the input comes from an HTTP activity or a lookup/asset read, confirm whether that step returned an empty/null value — that is the real fault to fix.
+
+## Resolution
+
+- **Null/unset variable:** ensure `JsonString` is assigned a non-null, non-empty value before the deserialize activity on every path that reaches it; add a guard/default if a branch can legitimately leave it unset.
+- **Null from upstream:** fix the producing activity so it returns the expected payload (e.g., an HTTP call that returned an empty body — see [deserialize-malformed-input.md](./deserialize-malformed-input.md) and the HTTP playbooks), or handle the empty result explicitly before deserializing.
+- **`DeserializeJsonArray` null-input hardening:** because `DeserializeJsonArray` does not guard null input (unlike `DeserializeJson`), validate the string is non-empty before the activity so the failure is an explicit check rather than a bare `NullReferenceException`.

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/deserialize-type-mismatch.md

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# Deserialize JSON — Type Mismatch (JsonSerializationException)
+
+## Context
+
+What this looks like:
+- A `UiPath.Web.Activities.DeserializeJson<T>` activity faults with `Newtonsoft.Json.JsonSerializationException`. The input is **well-formed JSON** (it parsed), but its shape does not fit the target type `T`. Typical messages:
+  - `Cannot deserialize the current JSON object (e.g. {"name":"value"}) into type '<T>' because the type requires a JSON array (e.g. [1,2,3]) to deserialize correctly.`
+  - `Cannot deserialize the current JSON array (e.g. [1,2,3]) into type '<T>' because the type requires a JSON object ...`
+  - `Error converting value "<x>" to type '<member type>'. Path '<member>', line N, position M.`
+  - `Could not cast or convert from System.String to <type>.`
+- Contrast with `JsonReaderException` (the JSON itself is invalid) — see [deserialize-malformed-input.md](./deserialize-malformed-input.md). Here the JSON is valid; the **target type** is the mismatch.
+
+What can cause it:
+- **Object/array shape mismatch** — `T` expects an array but the JSON is an object (or vice versa).
+- **Member type mismatch** — a field is a string where `T` expects a number/bool/date, or null where `T` expects a non-nullable value.
+- **Schema drift** — the API response shape changed (renamed/removed/retyped fields) while `T` (often generated from a `JsonSample`) stayed on the old shape.
+- **Wrong `T` chosen** — the `JsonObject` output type does not match the actual response contract.
+
+What to look for:
+- **The message's `Path` and member name** — pinpoints which field mismatched.
+- **`T` vs the actual JSON** — compare the target type (and the `JsonSample` it may have been generated from) against a current sample of the real response.
+- **Whether the response shape changed recently** — schema drift if earlier runs succeeded with the same `T`.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `JsonSerializationException` and `JobError.ActivityName` = the `DeserializeJson` activity. Confirm it is a serialization (type) error, not a `JsonReaderException` (malformed).
+2. **Read `T` and `JsonSample` from source** — the declared output type and the sample it was modeled on.
+3. **Get a current sample of the real input JSON** (the literal, the variable, or the upstream HTTP body) and compare it to `T` at the `Path` named in the message.
+4. **Decide object-vs-array, member-type, or drift** from the comparison.
+
+## Resolution
+
+- **Object/array mismatch:** change `T` to match the JSON shape (e.g., `List<...>` for an array, a single type for an object), or select the correct deserialize activity.
+- **Member type mismatch:** align the member type in `T` with the JSON (string vs number/bool/date; make it nullable if the field can be null), or fix the producer so the field's type is stable.
+- **Schema drift:** regenerate `T` from a current `JsonSample` of the real response and update downstream usages.
+- **Wrong `T`:** point `JsonObject` at the type that matches the actual response contract.

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/http-client-null-reference.md

@@ -0,0 +1,34 @@
+---
+confidence: medium
+---
+
+# HTTP Client — Null Reference (NullReferenceException)
+
+## Context
+
+What this looks like:
+- A `UiPath.Web.Activities.HttpClient` activity faults with `System.NullReferenceException: Object reference not set to an instance of an object.`
+- The exception is raised inside the activity while it builds the request (resolving endpoint, headers, cookies, parameters) or while reading the response — `HttpClient` does not wrap it.
+
+What can cause it:
+- **A request input resolves to null** — a workflow variable wired into `EndPoint`, a header value, a cookie value, a parameter, or the body evaluates to `Nothing` at runtime and is dereferenced during request building. (`EndPoint` is a required argument, but a bound variable can still evaluate to null.)
+- **Null upstream value** — the null came from a prior activity that returned nothing (e.g., an unset asset, an empty config read, an earlier HTTP call whose output was never set), then was passed into this activity.
+- **Response dereferenced after `ContinueOnError`** — a prior `HttpClient` with `ContinueOnError = True` returned an empty response, and a downstream expression reads `.Result` / a header off it.
+
+What to look for:
+- **Which input is null** — from the workflow source, list every variable feeding `EndPoint`, `Headers`, `Cookies`, `Parameters`, and `Body`, and trace where each is assigned.
+- **The activity immediately before** the faulted one — a common source of the null value.
+- **No HTTP status / transport phrase** in the message — distinguishes this from `WebException` ([http-request-connection-failure.md](./http-request-connection-failure.md)); a pure NRE means the request was never sent.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `System.NullReferenceException` and `JobError.ActivityName` = the `HttpClient` activity. The absence of any HTTP status code or transport phrase means the failure is in request building, not the call.
+2. **Enumerate the activity's inputs from source.** Capture every variable/expression feeding `EndPoint`, `Headers`, `Cookies`, `Parameters`, `Body`.
+3. **Trace each input to its assignment.** Find which one can be `Nothing` on the failing path — an unset variable, a no-result upstream activity, or a config/asset that was empty.
+4. **Check for an upstream `ContinueOnError` HTTP call** whose empty response is dereferenced here.
+
+## Resolution
+
+- **Null input variable:** ensure the variable is assigned a non-null value before the activity, or add a guard (validate / default it) on the path that reaches the HTTP Client.
+- **Null from an upstream activity:** fix the upstream activity so it returns a value, or handle its empty result explicitly before passing it on.
+- **Empty response after `ContinueOnError`:** check the prior call's `StatusCode` / result for success before dereferencing it; do not assume a response exists when `ContinueOnError` is on.

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/http-request-connection-failure.md

@@ -0,0 +1,48 @@
+---
+confidence: medium
+---
+
+# HTTP Client — Request Failed (WebException)
+
+## Context
+
+What this looks like:
+- A `UiPath.Web.Activities.HttpClient` activity faults with `System.Net.WebException`.
+- The job `Info` / `JobError.Type` names `System.Net.WebException`; the message is framework-originated (not a UiPath string), e.g.:
+  - `The remote server returned an error: (404) Not Found.` / `(401) Unauthorized.` / `(500) Internal Server Error.`
+  - DNS failure — `No such host is known. (<host>:<port>)` on modern .NET (`targetFramework: Windows`, .NET 6+; confirmed by repro on .NET 8) or `The remote name could not be resolved: '<host>'` on legacy .NET Framework
+  - `Unable to connect to the remote server`
+  - `The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel.`
+- The exception is the raw RestSharp/transport exception unwrapped from the request task — `HttpClient` does not wrap it.
+- **A timeout also surfaces as `System.Net.WebException` on modern .NET, with message `The operation has timed out.`** If that is the message, this is a timeout, not a connection failure — go to [http-request-timeout.md](./http-request-timeout.md).
+
+What can cause it (branch from the message):
+- **Non-success HTTP status (4xx/5xx)** — the server was reached and answered with an error status. `401/403` = auth/permission; `404` = wrong path/resource; `429` = rate limited; `5xx` = server-side fault.
+- **DNS resolution failure** (`remote name could not be resolved`) — wrong/typo'd host, or DNS not reachable from the robot machine.
+- **Connection refused / unreachable** (`Unable to connect`) — host up but port closed, service down, or firewall/proxy blocking egress.
+- **SSL/TLS failure** (`Could not establish trust relationship` / `secure channel`) — untrusted/expired server cert, or a TLS-version/proxy-interception mismatch.
+
+What to look for:
+- **The status code or transport phrase in the message** — selects the branch directly.
+- **`EndPoint` value** in the workflow source — confirm scheme/host/path are intended; a bare host gets `http://` prepended by the activity.
+- **`ContinueOnError`** — if `True`, the activity would NOT fault here; a faulted job means it is `False` (or the failure is elsewhere).
+- **Whether the same endpoint works from the robot machine** — isolates robot-network/proxy from a server-side problem.
+
+## Investigation
+
+1. **Capture the exact message + faulted activity.** `uip or jobs get <job-key> --output json` → `Info` (full message) and `JobError.ActivityName` / `WorkflowFilePath`. Confirm the activity is `HttpClient`.
+2. **Read the request configuration from source.** Open the workflow; capture `EndPoint`, `Method`, auth properties, and `EnableSSLVerification`.
+3. **Branch on the message:**
+   - Has an HTTP status code → server answered; go to step 4.
+   - "could not be resolved" / "Unable to connect" → transport/network; go to step 5.
+   - "SSL/TLS" / "trust relationship" → certificate/TLS; go to step 6.
+4. **Status-code branch.** Map the code: `401/403` → auth/permission on the target API; `404` → endpoint path/resource wrong or removed; `429` → throttling; `5xx` → target service fault (often transient — check whether earlier runs succeeded).
+5. **Transport branch.** Verify the host resolves and the port is reachable from the **robot machine** (not the author's machine). Check proxy/firewall egress rules.
+6. **TLS branch.** Check the server certificate validity/chain and the TLS version the endpoint requires; confirm the robot's trust store and that any intercepting proxy is trusted.
+
+## Resolution
+
+- **Non-success status:** fix per code — supply/refresh credentials or scope (`401/403`); correct the `EndPoint` path or resource id (`404`); add backoff / reduce call rate (`429`); for `5xx`, treat as a target-service fault — retry, or escalate to the API owner if persistent.
+- **DNS failure:** correct the host in `EndPoint`; ensure the robot machine can resolve it (DNS server / hosts entry / VPN).
+- **Connection refused / unreachable:** confirm the service is listening on the expected port and that the robot's network/proxy/firewall allows egress to it.
+- **SSL/TLS failure:** install/trust a valid server certificate (or fix the expired one); align the TLS version; trust the intercepting proxy's CA on the robot machine. Disabling `EnableSSLVerification` masks the problem and is not a fix for production endpoints.

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/http-request-timeout.md

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# HTTP Client — Request Timed Out (TimeoutException)
+
+## Context
+
+What this looks like:
+- A `UiPath.Web.Activities.HttpClient` activity faults with the message `The operation has timed out.` because the request exceeded `TimeoutMS` (default `6000` ms).
+- **The exception type is runtime-dependent** — verify both:
+  - Modern .NET (project `targetFramework: Windows`, .NET 6+): surfaces as **`System.Net.WebException: The operation has timed out.`** (the RestSharp request task faults and the raw transport exception is rethrown before the activity's explicit timeout path runs). Confirmed by repro on .NET 8.
+  - Legacy (.NET Framework 4.6.1, `Windows - Legacy`): `HttpClient` throws **`System.TimeoutException`** explicitly when RestSharp reports status `TimedOut`.
+  - Either way the **message is `The operation has timed out.`** — match on the message, not just the type. On modern .NET this overlaps with the connection-failure `WebException` ([http-request-connection-failure.md](./http-request-connection-failure.md)); the message text is the discriminator.
+- For the modern `NetHttpRequest` activity a timeout instead surfaces as `System.AggregateException` → inner `TaskCanceledException` — see [net-http-request-aggregate-failure.md](./net-http-request-aggregate-failure.md).
+
+What can cause it:
+- **Endpoint slower than `TimeoutMS`** — the server responds, but later than the configured budget (large payload, slow query, cold start).
+- **`TimeoutMS` set too low** — a tight timeout for an endpoint that is legitimately slow.
+- **Endpoint hung / not responding** — server overloaded or down; the request never completes.
+- **Network latency / proxy stall** between the robot machine and the endpoint.
+
+What to look for:
+- **`TimeoutMS` value** in the workflow source vs the endpoint's realistic response time.
+- **Whether the endpoint responds at all** when called manually from the robot machine, and how long it takes.
+- **Recent-runs pattern** — if earlier runs succeeded and only recent ones time out, the endpoint slowed or degraded (not a config change).
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `System.TimeoutException: The operation has timed out.` and `JobError.ActivityName` = the `HttpClient` activity.
+2. **Read `TimeoutMS` and `EndPoint` from source.** Note whether `TimeoutMS` is left at the `6000` ms default.
+3. **Measure the endpoint** from the robot machine (or an equivalent network position): does it respond, and in how long relative to `TimeoutMS`?
+4. **Check recent runs** for the same process (`uip or jobs list ... --output json`) — a shift from success to timeout points at endpoint degradation rather than a workflow change.
+
+## Resolution
+
+- **Endpoint legitimately slower than the budget:** raise `TimeoutMS` to cover the endpoint's real response time (with headroom).
+- **Endpoint hung / down:** treat as a target-service availability problem — retry, or escalate to the API owner; raising the timeout alone will not help a non-responding server.
+- **Network/proxy stall:** fix egress latency / proxy configuration on the robot machine.
+- **Genuinely long operation:** if the endpoint is expected to take a long time, combine a higher `TimeoutMS` with a retry/backoff around the activity rather than an unbounded wait.

package/skills/uipath-troubleshoot/references/activity-packages/web-activities/playbooks/net-http-request-aggregate-failure.md

@@ -0,0 +1,38 @@
+---
+confidence: medium
+---
+
+# HTTP Request (NetHttpRequest) — Aggregate Exception
+
+## Context
+
+What this looks like:
+- A `UiPath.Web.Activities.NetHttpRequest` (modern **HTTP Request**) activity faults with `System.AggregateException` and the message `One or more errors occurred. (<inner message>)`.
+- `NetHttpRequest` runs an async pipeline over `System.Net.Http.HttpClient` with a retry policy; when the pipeline faults the task exception surfaces as an `AggregateException` **wrapper**. The real cause is the inner exception.
+- Note: `NetHttpRequest` defaults `ContinueOnError = True`, so HTTP error statuses (4xx/5xx) normally do NOT fault — they return a response summary. A faulted job means either `ContinueOnError = False` or a transport/timeout/setup failure the pipeline could not turn into a response.
+
+What can cause it (read the inner exception):
+- **Inner `System.Net.Http.HttpRequestException`** — transport/HTTP failure after retries: DNS resolution failure, connection refused, SSL/TLS handshake failure, or (when `ContinueOnError = False`) a non-success status the retry policy exhausted.
+- **Inner `System.Threading.Tasks.TaskCanceledException` / `TimeoutException`** — the request exceeded `TimeoutInMiliseconds` (default `10000` ms). See [http-request-timeout.md](./http-request-timeout.md) for the legacy analog.
+- **Inner validation/setup exception** — bad `RequestUrl`, unresolved `ConnectionId`, or invalid auth configuration surfaced during input preprocessing.
+
+What to look for:
+- **`InnerException` / `InnerExceptions` type and message** — the decisive signal; the `AggregateException` text alone is not enough.
+- **`RequestUrl`, `TimeoutInMiliseconds`, `RetryCount`, `ContinueOnError`, `AuthenticationType`** from the workflow source.
+- **Trace spans** — expose the request URL, attempt count, and HTTP status across retries.
+
+## Investigation
+
+1. **Confirm the signature + activity.** `uip or jobs get <job-key> --output json` → `Info` shows `System.AggregateException`; `JobError.ActivityName` = the `NetHttpRequest` activity.
+2. **Unwrap the inner exception.** Read the inner type/message from the `Info` stack (and from `uip or jobs traces <job-key> --output json` / `uip traces spans get --job-key <job-key> --output json`). This selects the branch.
+3. **Branch on the inner exception:**
+   - `HttpRequestException` → transport/status: apply [http-request-connection-failure.md](./http-request-connection-failure.md) (DNS / connection / TLS / status).
+   - `TaskCanceledException` / `TimeoutException` → timeout: apply [http-request-timeout.md](./http-request-timeout.md) against `TimeoutInMiliseconds`.
+   - validation/setup → fix the named input (`RequestUrl`, `ConnectionId`, auth).
+4. **Read the request configuration from source** to confirm the branch (URL, timeout, retry, auth).
+
+## Resolution
+
+- **Resolve by inner cause, not the wrapper.** Map the unwrapped inner exception to its fix using the cross-referenced playbook above (connection/status, or timeout).
+- **Validation/setup inner exception:** correct the offending input — fix `RequestUrl`, resolve/select a valid `ConnectionId`, or supply the credentials/token the chosen `AuthenticationType` requires.
+- **Retry exhausted on a transient fault:** raise `RetryCount` / adjust the retry policy if the endpoint is intermittently slow, but only after confirming the inner cause is genuinely transient.

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

@@ -0,0 +1,13 @@
+# Web Activities Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for `UiPath.Web.Activities` investigations. These activities propagate raw .NET / Newtonsoft / RestSharp exceptions (no package-specific wrapper), so the **faulted activity class + exception class** is the primary discriminator.
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| HTTP Client — Request Failed | Medium | `HttpClient` faults with `System.Net.WebException` — the outbound call failed: non-success HTTP status (4xx/5xx), DNS resolution failure (`No such host is known.` on .NET 6+ / `The remote name could not be resolved` on legacy), connection refused (`Unable to connect to the remote server`), or SSL/TLS (`Could not establish trust relationship for the SSL/TLS secure channel`). Branch from the message. | [http-request-connection-failure.md](./playbooks/http-request-connection-failure.md) |
+| HTTP Client — Request Timed Out | Medium | `HttpClient` request exceeds `TimeoutMS` (default 6000 ms), message `The operation has timed out.` — type is runtime-dependent: `System.Net.WebException` on .NET 6+ (confirmed by repro on .NET 8), `System.TimeoutException` on legacy .NET Framework. Match on the message. (`NetHttpRequest` timeouts arrive as `AggregateException`→`TaskCanceledException`.) | [http-request-timeout.md](./playbooks/http-request-timeout.md) |
+| HTTP Client — Null Reference | Medium | `HttpClient` faults with `System.NullReferenceException` during request building — a request input (`EndPoint`, header, cookie, parameter, body) resolved to null, often from an unset variable or a no-result upstream activity. No HTTP status in the message means the request was never sent. | [http-client-null-reference.md](./playbooks/http-client-null-reference.md) |
+| HTTP Request (NetHttpRequest) — Aggregate Exception | Medium | `NetHttpRequest` faults with `System.AggregateException` wrapping the real cause. Unwrap `InnerException`: `HttpRequestException` (DNS/connection/TLS/status) or `TaskCanceledException` (timeout vs `TimeoutInMiliseconds`, default 10000 ms). Defaults `ContinueOnError = True`, so a fault is transport/timeout/setup, not a plain 4xx/5xx. | [net-http-request-aggregate-failure.md](./playbooks/net-http-request-aggregate-failure.md) |
+| Deserialize — Malformed JSON / XML Input | High | `DeserializeJson` / `DeserializeJsonArray` throw `Newtonsoft.Json.JsonReaderException` and `DeserializeXml` throws `System.Xml.XmlException` when the input string is not valid JSON/XML (HTML error page, empty/partial body, wrong encoding, object-vs-array). The `line`/`position` localizes the defect. **Most common cause: an upstream `HttpClient`/`NetHttpRequest` returned a non-payload body** — diagnose the HTTP call. | [deserialize-malformed-input.md](./playbooks/deserialize-malformed-input.md) |
+| Deserialize JSON — Type Mismatch | Medium | `DeserializeJson<T>` throws `Newtonsoft.Json.JsonSerializationException` when well-formed JSON does not fit the target type `T` (object-vs-array, member type mismatch, schema drift, wrong `T`). The message `Path` names the offending member. | [deserialize-type-mismatch.md](./playbooks/deserialize-type-mismatch.md) |
+| Deserialize — Null / Empty Input | High | Input string is null/empty. `DeserializeJson` guards it → `System.ArgumentNullException (Parameter 'JSON string')`; `DeserializeJsonArray` has no guard → `System.NullReferenceException`. Usually an unassigned variable or a null upstream value. | [deserialize-null-input.md](./playbooks/deserialize-null-input.md) |

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

@@ -0,0 +1,55 @@
+# Word Activities Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity's namespace and class match the reported failure (`UiPath.Word.Activities.WordApplicationScope`, `UiPath.Word.Activities.WordReplaceText` / `ReplaceTextInDocument`, and `Read Text`). Classic `Word Application Scope` (Interop) and the modern `Use Word File` surface share intent but run different code paths — treat them as different. For `Read Text`, also distinguish the **Word-pack** activity (needs a container) from the **standalone** `System > File > Word Document` `Read Text` (takes a file path, `.docx`-only) — they fail for different reasons. A substitution/extraction fault is distinct from a scope-level fault: the scope opened fine and the failure is in the activity. `Export to PDF` (`WordExportToPdf`) faults are about the **output** (missing directory, malformed path) or **COM** (orphaned WINWORD), not the document content. `Append Text` (`WordAppendText`) has the same App-Integration-vs-standalone split as Read Text (container required vs file path), plus a 0-byte-file ("Archive file cannot be size zero") signature; its install / lock / version faults are shared with the scope-level playbooks.
+- **Faulting frame** — the deepest `UiPath.Word.*` stack frame routes to the right playbook: `WordAppHelpers.StartNewApplication` / `ComAppReferenceCountManager.StartOrAttach` = COM **start** failure (Word couldn't launch — background/Session-0, not-installed, or broken registration); `WordDocumentFactory.OpenOrCreateNewDocument` / `Documents.Open` = **open** failure (bad or URL `FilePath`); a child cast to `_Document` (IID `{0002096B-...}`) = **wrong-thread** apartment fault. Do not apply one signature's cause to a different frame. For a COM-start failure on an unattended run, read `runtimeOptions.requiresUserInteraction` in `project.json`: `false` ⇒ Background Process ⇒ Session 0 with no interactive session (the primary COM-start cause).
+- **Document** — the document path in evidence matches the file the user is asking about. A scope pointed at a different document is unrelated data.
+- **Robot / machine identity** — the robot account and the machine where Word is installed match the one the user reports. Word installation, bitness, activation state, and Trust Center settings are per-user-per-machine, so evidence from a different host is not transferable.
+- **Office version and bitness** — the Word/Office version and bitness installed on the robot machine match what the user reports. Bitness mismatch with the robot process is a known COM-interop cause; multiple Office installs produce dispatcher ambiguity.
+- **Package version** — the `UiPath.Word.Activities` version referenced in `project.json` matches what is installed on the execution host. A "cannot create unknown type" error is a version/restore mismatch, not a runtime defect.
+- **Timestamp** — the failure occurred during the time window the user reported. Load-bearing for hang/COM investigations (a transient lock or background dialog may not reproduce on demand).
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## What to Capture
+
+1. **Workflow source** — read the `WordApplicationScope` node from the `.xaml` to capture the literal document `Path` expression, `CreateIfNotExists`, `Password`, and whether the scope runs visible or unattended. Property-panel summaries truncate; the XAML is authoritative.
+2. **Word installed + bitness** — whether desktop Word is installed on the execution host (`Control Panel > Programs and Features`, or `HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\winword.exe`), and the Office bitness (`File > Account > About Word`) versus the robot process bitness.
+3. **Robot type** — whether the host is a Linux/container robot that cannot run Interop at all.
+4. **Process state at failure time** — whether WINWORD.EXE was already running or orphaned, and whether any modal dialog (password, recovery sidebar, Safe Mode, activation, Protected View) was open. Without `Visible = True`, dialogs are invisible but still block COM calls.
+5. **Document path resolution** — the concrete path the dynamic expression resolves to on the robot host (not the developer machine), whether the file exists there, and whether it is held open by a sync client, antivirus, or a concurrent job.
+6. **Package version** — `UiPath.Word.Activities` version in `project.json` versus the version restored on the execution host, especially for remote/Orchestrator runs.
+7. **Replace Text inputs + outcome** — for `Replace Text in Document` faults, capture the `Search` and `Replace` expressions (and their runtime lengths — 256 chars is the classic cap), whether the activity threw or succeeded-with-no-change, and whether it sits inside a loop with `Auto Save` enabled. For a silent miss, inspect the template's placeholder for run-splitting / mixed formatting; trace the **output document content**, not just the absence of an exception.
+8. **External Word state + run surface** — for a COM wrong-thread fault (`0x8001010E`), whether `WINWORD.EXE` was already running when the run started and whether it stayed open through the operation, plus the run surface (foreground Studio vs unattended / Session 0 / background) and whether the faulting activity runs on a non-creator thread (Parallel/Pick/Invoke/coded). The fault depends on an externally-owned instance and the apartment the proxy is accessed from.
+
+## Testing Prerequisites
+
+When testing hypotheses for `Word Application Scope` issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — confirm the faulted activity is `UiPath.Word.Activities.WordApplicationScope` and not the modern `Use Word File` activity, which runs a different code path.
+2. **Document path** — exact path bound to the scope, resolved against the robot's working directory at run time (relative paths resolve against the project folder, not the document folder).
+3. **Word installation + bitness** — desktop Word present on the robot machine and its bitness relative to the robot process. The user (or someone with desktop access) must check; it cannot be inferred from job logs.
+4. **Interactive state** — whether a background dialog was blocking. Reproduce with the scope visible to confirm.
+5. **Package version** — `UiPath.Word.Activities` version available on the execution host, compared against `project.json`.
+
+When testing hypotheses for `Replace Text in Document` issues:
+
+1. **Activity surface** — classic `WordReplaceText` (inside `Word Application Scope`) vs modern `ReplaceTextInDocument` (inside `Use Word File`). The 256-char limit is a classic-version constraint.
+2. **Search / Replace values** — the literal expressions and their .NET string lengths at run time; confirm an exact character-for-character match against the on-screen placeholder for a silent miss, and check >256 chars for the length-limit hypothesis.
+3. **Throw vs no-op** — whether the activity raised an exception (COM busy, file lock, ArgumentException) or completed with the document unchanged (run-split placeholder). A clean run with no substitution points at the template, not an exception path.
+
+When testing hypotheses for `Read Text` issues:
+
+1. **Which Read Text surface** — Word-pack `Read Text` (requires a `Use Word File` / `Word Application Scope` container) vs standalone `System > File > Word Document` `Read Text` (own file path, `.docx`-only). The container vs format failures are surface-specific.
+2. **Container placement** — whether the Word-pack `Read Text` is nested inside a scope; a design-time validation warning / runtime invalid-context fault points at missing-container.
+3. **File format + origin** — for the standalone activity, whether the input is legacy `.doc` (unsupported, `.docx`-only) and whether the file came from email/internet/external share (Mark-of-the-Web → Protected View block).
+
+When testing hypotheses for `Export to PDF` (`WordExportToPdf`) issues:
+
+1. **Output path** — capture the literal output File Path. Does the **parent folder exist** on the host (missing folder → generic `Command Failed`)? Does it end in `.pdf` with one clean separator and no empty variable segments (malformed path → save failure)?
+2. **Generic `Command Failed` carries no detail** — disambiguate by checking folder existence and path format before assuming COM.
+3. **COM state** — for a hang/crash/`COMException`, check for orphaned `WINWORD.EXE` and whether the input document is locked/open elsewhere.
+4. **Package vs Studio version** — for a `TargetInvocationException`, compare `UiPath.Word.Activities` against the Studio version (same as the Replace Text version-mismatch case).

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

@@ -0,0 +1,82 @@
+# Word Activities
+
+Activities from the `UiPath.Word.Activities` package for automating Microsoft Word documents on Windows. Activities run inside a scope container that opens a single `.docx`/`.doc`/`.dotx` and exposes it to the child activities: the modern `Use Word File` (`WordProcessScope`) or the classic `Word Application Scope` (`UiPath.Word.Activities.WordApplicationScope`). Most document operations — including `Add Picture` — drive a real `WINWORD.EXE` instance through Office Interop (COM), so the package depends on a working, matching-bitness Microsoft Word install on the robot host.
+
+A separate file-based path exists for hosts where Office is missing or locked down: the `Word Document` activities (Studio activity panel under **System > File > Word Document**, e.g. `WordDocumentScope`) read/write the `.docx` through the document object model without launching Word. They do not support every COM-only operation, but cover common read/insert tasks and are the migration target when COM interop cannot be made reliable.
+
+## How Word Application Scope Executes
+
+`Word Application Scope` opens a `.docx`/`.doc`/`.dotx` document inside a COM-backed WINWORD.EXE session, runs the child activities against that open document, then saves and closes. Behaviour chain:
+
+1. Create the `Word.Application` COM instance (requires registered desktop Word; bitness must be compatible with the robot process)
+2. Open the document at the configured path (or create it when `Create if not exists` is set)
+3. Run child activities against the open document
+4. Save and close, releasing the WINWORD.EXE handle
+
+Failures originate at distinct layers — COM/Interop availability (step 1), file resolution and locks (step 2), interactive prompts that block COM (any step), or package/type loading (before step 1). Knowing which layer produced the error narrows the investigation.
+
+## Add Picture (WordAddImage)
+
+`Add Picture` (`UiPath.Word.Activities.WordAddImage`) inserts an image into the Word document opened by its parent scope. Behaviour chain:
+
+1. Resolve the open document handle from the surrounding `Use Word File` / `Word Application Scope`.
+2. Read the image from the path in the `Picture to insert` (`ImagePath`) property — a file path string, not an in-memory image object.
+3. Locate the insertion point from `Insert relative to` — `Text` (a literal anchor string), `Bookmark` (a named bookmark), or `Document` (`Start` / `End`).
+4. Insert the image at the resolved point and commit it to the document.
+
+Failures can originate at any layer — scope/context (step 1), file path or image format (step 2), target resolution (step 3), or COM interop with Word itself (any step).
+
+Key properties: `ImagePath` ("Picture to insert" — fully-qualified absolute path or an exact relative path string), `InsertRelativeTo` ("Insert relative to" — `Text` / `Bookmark` / `Document`), the corresponding anchor (`Text` string, `BookmarkName`, or `Position` = `Start`/`End`), and sizing options (`Width` / `Height`).
+
+## Replace Text in Document
+
+`Replace Text in Document` finds a `Search` string in the document opened by the surrounding scope and substitutes `Replace`. Classic `WordReplaceText` runs inside `Word Application Scope` (Interop); modern `ReplaceTextInDocument` runs inside `Use Word File`. They share a display name but run different code paths — treat them as distinct. Classic versions cap `Search`/`Replace` at 256 characters. A failure here is distinct from a scope-level fault: the scope opened fine; the failure is in the substitution (an exception, or a silent success with the document unchanged).
+
+## Read Text
+
+`Read Text` extracts the document's text. Two distinct surfaces fail for different reasons: the **Word-pack** `Read Text` reads the document held open by a surrounding `Use Word File` / `Word Application Scope` (it has no file input of its own); the **standalone** `Read Text` under `System > File > Word Document` takes a file path directly (no container) but is OpenXML `.docx`-only.
+
+## Export to PDF
+
+`Export to PDF` (`WordExportToPdf`, also "Save Document as PDF") exports the open document to a PDF at a target path, via Word Interop inside a `Word Application Scope`. It does **not** auto-create the output directory. Faults are about the **output** (missing target folder, malformed path) or **COM** (orphaned `WINWORD.EXE` / locked input), not the document content.
+
+## Append Text
+
+`Append Text` (`WordAppendText`) appends text to the document. Like Read Text, it has two surfaces: the **App-Integration** `Append Text` appends to the document held open by a surrounding `Word Application Scope` / `Use Word File` (no file input of its own); the **standalone** `Append Text` under the **Word Document** category takes a file path directly (no container, no Word install needed).
+
+## Key Activities
+
+- **Word Application Scope** (`WordApplicationScope`, display name "Word Application Scope") — open a Word document via Interop and run child activities against it. **COM-only** — requires desktop Word. Properties include the document `Path`, `CreateIfNotExists` (generate the file when absent), and `Password`.
+- **Add Picture** (`WordAddImage`, display name "Add Picture") — insert an image into the document opened by the parent scope; see the `Add Picture` execution model above.
+- **Replace Text in Document** (modern `ReplaceTextInDocument` inside `Use Word File`, classic `WordReplaceText` inside `Word Application Scope`) — find a `Search` string and substitute `Replace`. Classic versions cap `Search`/`Replace` at 256 characters.
+- **Read Text** (display name "Read Text") — extract the document's text. Word-pack `Read Text` reads the document held open by a surrounding `Use Word File` / `Word Application Scope` (no file input of its own); the standalone `System > File > Word Document` `Read Text` takes a file path directly but is OpenXML `.docx`-only.
+- **Export to PDF** (`WordExportToPdf`, display name "Export to PDF" / "Save Document as PDF") — export the open document to a PDF at a target path, via Interop inside a `Word Application Scope`. Does **not** auto-create the output directory.
+- **Append Text** (`WordAppendText`, display name "Append Text") — append text to the document. App-Integration `Append Text` appends to the document held open by a surrounding `Word Application Scope` / `Use Word File` (no file input of its own); the standalone `Word Document` `Append Text` takes a file path directly (no container, no Word install needed).
+
+## Common Failure Patterns
+
+- **Word not installed / COM interop failure** — the scope faults at startup creating the COM instance. Surfaces as `Error opening document, make sure Word application is installed`, `REGDB_E_CLASSNOTREG` (`80040154`), or `Could not load ... Microsoft.Office.Interop.Word`. Causes: no desktop Word (web-only Office, Linux/container robot), 32-bit/64-bit Office–robot bitness mismatch, or damaged Office COM registration. Package-wide environmental failures (type library not registered, bitness mismatch, Word busy/blocked `0x8001010A`, `WINWORD.EXE` crashing mid-operation with `RPC_E_WRONG_THREAD` `0x8001010E`) are documented in [word-com-interop-failures.md](./playbooks/word-com-interop-failures.md).
+- **"The file appears to be corrupted"** — opening/saving fails reporting corruption. Causes: an orphaned WINWORD.EXE holding the file lock, an in-place template overwrite leaving a half-written source, or Protected View / Mark-of-the-Web blocking the write.
+- **Workflow hangs / freezes indefinitely** — WINWORD.EXE is up but unresponsive because Word opened a background modal prompt (password, document-recovery sidebar, Safe Mode, activation, trust-this-file). When the scope runs invisibly, the dialog still wedges the COM calls.
+- **"Cannot create unknown type WordApplicationScope"** — load/compile-time failure: the execution host lacks the `UiPath.Word.Activities` package 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.
+- **File path verification errors** — the document path does not resolve at runtime. Causes: opening a file that should be created (`Create if not exists` unset), a relative path resolved against the wrong working directory, a dynamically built path constructed incorrectly, or an unavailable mapped drive / unhydrated cloud placeholder.
+- **Add Picture — activity outside a Word scope** — `Add Picture` is placed standalone, or in a sequence not nested inside a `Use Word File` / `Word Application Scope`. It faults immediately or shows a design-time validation error. `Add Picture` has no document handle of its own — it only operates on the document its parent scope opened. This is a configuration/structure error, not a runtime COM fault.
+- **Add Picture — insertion target not found** — `Insert relative to` is set to `Text` or `Bookmark`, but the anchor does not exist in the open document. Causes: the `Text` anchor string does not match the document exactly (case-sensitive), the named bookmark does not exist in that document, or the anchor was present in a template but not the actual document instance opened at runtime.
+- **Add Picture — invalid path or unusable image** — `Add Picture` faults with a file-not-found error or a generic exception while reading the image. Causes: a relative `Picture to insert` path that does not resolve under the robot's working directory, a missing/moved file, or an in-memory `UiPath.Core.Image` variable fed into the field instead of a path string. `Add Picture` expects a fully-qualified absolute path (or an exact relative path) to an image file on disk.
+- **Replace Text — placeholder not replaced (silent)** — no exception, but the placeholder is unchanged because Word split it across internal XML runs (the token was edited/backspaced/reformatted in place), so the exact-string search never matches the contiguous term. Trace the output document content, not just the absence of an exception.
+- **Replace Text — input string length limit** — classic versions enforce a hard 256-character cap on `Search`/`Replace`; longer values raise `ArgumentException` or truncate silently. Relaxed in current package versions.
+- **Read Text — activity outside its container** — the modern Word-pack `Read Text` warns at design time / faults at runtime as invalid because it has no file input of its own and was dropped outside a `Use Word File` / `Word Application Scope`. Fix: nest it in a container, or use the standalone `System > File > Word Document` `Read Text` (takes a file path).
+- **Read Text — standalone System Read Text fails on .doc** — the `System > File > Word Document` `Read Text` is OpenXML `.docx`-only and errors / returns nothing on legacy binary `.doc`. Fix: read `.doc` through a `Use Word File` (Interop reads both formats), or convert to `.docx` first.
+- **Read Text — Protected View blocks an externally-sourced file** — 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.
+- **Export to PDF — "Command Failed" (output directory missing)** — `Export to PDF` faults with a generic `Command Failed` because the target folder doesn't exist; the activity won't auto-create it. Fix: `Create Folder` before the export.
+- **Export to PDF — malformed output path / missing `.pdf`** — the File Path is built from unformatted concatenation (no `.pdf` suffix, missing/doubled separator, empty variable segment). Fix: `Path.Combine(folder, name & ".pdf")` and validate the pieces.
+- **Export to PDF — COM interop hang / crash / `COMException`** — an orphaned `WINWORD.EXE` or a locked input document blocks the export's COM call. Fix: Kill Process WINWORD before the scope, ensure the input is free; persistent → an Invoke Code C# `ExportAsFixedFormat` fallback.
+- **Append Text — "Activity is valid only inside WordApplicationScope"** — the App-Integration `Append Text` is outside a `Word Application Scope` / `Use Word File`; it has 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 — "Archive file cannot be size zero"** — the target `.docx` is a 0-byte file (a renamed `.txt`, or a failed/truncated write), not a valid OpenXML package. Fix: delete it + `Create if not exists`, or fix the upstream that produced the empty file.
+- **COM wrong-thread cast (`0x8001010E RPC_E_WRONG_THREAD`)** — a child activity (commonly `Save Document as PDF`) faults casting `System.__ComObject` to `Microsoft.Office.Interop.Word._Document` (IID `{0002096B-...}`). The document proxy was created on one STA apartment and accessed from another. Causes: the scope attached to an already-open external Word; that external Word closed mid-run; an off-STA / non-interactive runtime (unattended / Session 0 / background); or a thread other than the scope creator (Parallel/Pick/Invoke/coded). Distinct from `0x80010108 RPC_E_DISCONNECTED` (the Word server died outright). See [word-export-pdf-com-wrong-thread.md](./playbooks/word-export-pdf-com-wrong-thread.md).
+
+## Package
+
+NuGet: `UiPath.Word.Activities`
+
+Version-specific bugs are documented in the relevant playbooks.

package/skills/uipath-troubleshoot/references/activity-packages/word-activities/playbooks/add-picture-failures.md

@@ -0,0 +1,51 @@
+---
+confidence: medium
+---
+
+# Add Picture (WordAddImage) Failures
+
+## Context
+
+`Add Picture` (`UiPath.Word.Activities.WordAddImage`) fails to insert an image into a Word document. The failure falls into one of four distinct categories, each with its own signature and fix. Identify the category first, then apply the matching resolution.
+
+What this looks like:
+- A design-time validation warning that the activity is invalid, or an immediate fault when the activity is reached
+- A Word COM HRESULT — `Unable to cast COM object ... 0x8002801D` or `The application is busy ... 0x8001010A`, or Word (`WINWORD.EXE`) faulting and closing mid-insert with a `RPC_E_WRONG_THREAD ... 0x8001010E` cast error (see C2)
+- A missing-reference error — the bookmark or text anchor where the image should go cannot be found
+- A file-not-found or generic exception while reading the `Picture to insert` value
+
+What can cause it — four distinct mechanisms:
+
+- **C1. Activity outside a Word scope.** `Add Picture` is not nested inside a `Use Word File` (`WordProcessScope`) or `Word Application Scope`. It has no document handle of its own — outside a scope there is no document to insert into, so it is invalid. Faults synchronously or shows a design-time validation error. (A common variant: `Add Picture` lives in an `Invoke Workflow File` child and the scope's document context does not cross the invoke boundary.)
+- **C2. COM / Interop exception or Word process crash.** The Word COM layer faults, or `WINWORD.EXE` itself crashes mid-insert and the activity then throws a COM cast / `RPC_E_WRONG_THREAD` (`0x8001010E`) error on its async-completion path. This is an **environmental / host-level** failure that is not specific to `Add Picture` (it can hit any Word activity), so its full signature set, decision tree, and fixes live in the package-level playbook **[word-com-interop-failures.md](./word-com-interop-failures.md)** (causes E1 type-library/class not registered, E2 bitness mismatch, E3 busy/blocked, E4 Word process crash). One trigger that *is* Add-Picture-specific: inserting a very large but otherwise valid image — `Add Picture` has no resize property, so a multi-megapixel image is handed to Word at full resolution and can crash it (E4).
+- **C3. Insertion target not found.** `Insert relative to` is `Text` or `Bookmark`, but the anchor does not exist in the open document. Text matching is **case- and whitespace-sensitive**; the named bookmark may be a typo, may live only in a template, or may have been removed upstream. (`Insert relative to = Document` has no anchor dependency.)
+- **C4. Invalid path or unusable image.** `Picture to insert` (`ImagePath`) cannot be read. Causes: an in-memory `UiPath.Core.Image` variable was bound instead of a path string; a relative path that does not resolve under the Robot account; a missing/moved file (UNC unreachable, drive not mapped, OneDrive placeholder); or a path typo / extension-casing mismatch.
+
+## Causes
+
+Name the confirmed sub-cause exactly. Do NOT assert a cause unless the investigation decision tree arrived at it.
+
+- **C1.** Activity 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](./word-com-interop-failures.md)**.
+- **C3.** Insertion target (text/bookmark) not found in the open document.
+- **C4.** Invalid path or unusable image fed to `Picture to insert`.
+
+## Investigation
+
+1. **Read the error signature** from job evidence and the `Add Picture` configuration from the `.xaml`. Match against the decision tree below; stop at the first match.
+2. **Decision tree:**
+   - Design-time "invalid activity" validation error, or a missing-scope/context message → **C1**. Confirm in the `.xaml` that no ancestor of `Add Picture` is a `Use Word File` / `Word Application Scope` (and that the document context is not lost across an `Invoke Workflow File` boundary).
+   - Error contains a COM HRESULT (`0x8002801D`, `0x8001010A`, `0x8001010E`, or related), **or** Word (`WINWORD.EXE`) faulted/closed mid-insert → **C2**. This is a host/COM-layer failure shared by all Word activities — switch to **[word-com-interop-failures.md](./word-com-interop-failures.md)** and follow its decision tree (E1 type-library/class not registered, E2 bitness, E3 busy/blocked, E4 Word process crash). Note for `Add Picture` specifically: a very large but valid image can crash Word on insert (E4), since the activity has no resize property.
+   - Error references a missing bookmark or an unlocatable text anchor → **C3**. Read `InsertRelativeTo` and its anchor (`Text` string / `BookmarkName`), open the document the scope actually opened, and search for the anchor exactly (case + whitespace for text; the bookmark list for bookmarks). Confirm the opened file is the intended document, not a template or stale copy.
+   - File-not-found or a generic exception reading the image → **C4**. Read the `ImagePath` binding and its type. If it is a `String`, resolve it to a concrete path and confirm the file exists on the robot host under the Robot's Windows user; if relative, determine the working directory it resolves against at runtime. If it is an `Image`/object variable, that is the cause.
+
+## Resolution
+
+Apply the fix for the identified sub-cause.
+
+- **C1 — outside a scope:** wrap `Add Picture` in a `Use Word File` (preferred) or `Word Application Scope` pointed at the target document, and move the activity into the scope body. If it sits in an invoked child workflow, open the scope in that child or move the activity into the parent — scope context does not cross the invoke boundary implicitly. If the structure looks correct but validation still flags it, confirm `UiPath.Word.Activities` is installed and restored in `project.json`.
+- **C2 — COM / Interop or Word crash:** apply the fixes in **[word-com-interop-failures.md](./word-com-interop-failures.md)** for the identified host cause (E1 online-repair of Office; E2 match bitness; E3 clear orphaned `WINWORD.EXE` / dismiss modal / unblock downloaded files; E4 Word process crash). The XAML is correct — do not edit it. For an `Add Picture`-specific E4 crash on a large image, **pre-resize the image before inserting it** (the activity has no resize property), use a smaller image, or insert via `Paste Chart/Picture Into Document`. If Office cannot be made reliable, migrate to the file-based `Word Document` activities (System > File > Word Document).
+- **C3 — target not found:** correct the `Text` anchor to match the document exactly (case + whitespace) or normalize the document text; add or fix the `BookmarkName` so it points at a bookmark that exists in that document. If only top/bottom placement is needed, switch `Insert relative to` to `Document` with `Position` = `Start` / `End` to drop the anchor dependency entirely. If the wrong document was opened, fix the scope's file path.
+- **C4 — invalid path / image:** if an in-memory `UiPath.Core.Image` was bound, save it to disk first with `Save Image` and pass that path string. Use a fully-qualified **absolute** path (e.g. `C:\Images\chart.png`) or build one explicitly (`Path.Combine(...)`) so it resolves identically under the Robot account. Ensure the file is present and readable on the robot host under the Robot's Windows user.
+
+If a COM HRESULT or Word crash (C2) persists after all environmental causes are ruled out, follow the escalation guidance in **[word-com-interop-failures.md](./word-com-interop-failures.md)** (capture a `Verbose` robot log plus a Process Monitor trace and/or a ProcDump crash dump of `WINWORD.EXE`, and the offending image) and open a UiPath support case.