@uipath/skills 1.198.0-preview.21 → 1.199.0-preview.106

package/skills/uipath-troubleshoot/references/activity-packages/file-operations/playbooks/download-file-httpclient-reused-in-loop.md

@@ -0,0 +1,34 @@
+---
+confidence: medium
+---
+
+# Download File from URL — "This instance has already started one or more requests"
+
+## Context
+
+What this looks like:
+- `Download File from URL` faults with `This instance has already started one or more requests. Properties can only be modified before sending the first request.` (a `System.InvalidOperationException` from `System.Net.Http.HttpClient`).
+- The failure appears on the **second (or a later) iteration** when the activity runs inside a `For Each` / loop downloading multiple files; the first download often succeeds.
+
+What can cause it:
+- **Reused / improperly-disposed HTTP client across loop iterations.** The underlying `HttpClient` from the first download is still occupied (or was disposed and is being reused), so the next iteration cannot start a fresh request — `HttpClient` forbids changing properties / starting requests on an instance that already sent one.
+
+What to look for:
+- Whether `Download File from URL` sits inside a `For Each` / `While` loop over multiple URLs.
+- Whether the failure is iteration-dependent (first item works, later items fail) — the signature of client-lifecycle reuse, not a per-URL problem.
+
+## Investigation
+
+1. Read the error from job evidence; confirm it is `This instance has already started one or more requests` at `Download File from URL` (an `HttpClient`/`InvalidOperationException`), not an HTTP status, DNS, or file-finalize error.
+2. Read the `.xaml`: confirm the download activity is inside a loop, and how the HTTP client / download is structured per iteration.
+3. Confirm the timing — first iteration succeeds, a later one fails — pointing at client reuse rather than a bad URL.
+
+## Resolution
+
+- **Instantiate a fresh HTTP client per iteration (preferred):** add an `Assign` immediately before the download inside the loop so each iteration uses a clean client — `httpClient = New System.Net.Http.HttpClient()` (variable type `System.Net.Http.HttpClient`).
+- **Force release after each download (alternative):** drag an `Invoke Code` block right after the download step to release the prior client's resources:
+  ```vbnet
+  GC.Collect()
+  GC.WaitForPendingFinalizers()
+  ```
+- **General:** ensure each loop iteration owns its own request lifecycle (new client per item, or a properly scoped/disposed client) so no instance is asked to start a second request.

package/skills/uipath-troubleshoot/references/activity-packages/file-operations/playbooks/download-file-stuck-tmp.md

@@ -0,0 +1,29 @@
+---
+confidence: medium
+---
+
+# Download File from URL — Downloaded File Stuck as .tmp
+
+## Context
+
+What this looks like:
+- `Download File from URL` reports success, but a **downstream step fails** because the saved file is a temporary file — e.g. `document.xlsx.tmp` instead of `document.xlsx` — so `Read Range` / `Read CSV` / a path check on the real name can't find it.
+
+What can cause it:
+- **The download/finalize raced.** The activity streams the body to a `*.tmp` file and then renames it to the final name; when downstream activities run before the network stream is fully flushed and the file is finalized, the path is still the `.tmp`. A slow/large transfer or an eager next step makes the workflow "move too fast" for the file system.
+
+What to look for:
+- Whether the immediate next step references the **final** file name/extension, and whether it intermittently finds a `*.tmp` instead.
+- Whether the failure is intermittent (timing-dependent) rather than every run.
+
+## Investigation
+
+1. Read the error from job evidence; confirm the download "succeeded" but a later step fails resolving the target file, and that a `*.tmp` artifact is involved.
+2. Read the `.xaml`: what consumes the downloaded file immediately after, and does it expect the final extension?
+3. Confirm the failure is timing-dependent (intermittent), the signature of a finalize race rather than a wrong path.
+
+## Resolution
+
+- **Wrap the download in a Retry Scope (preferred):** put `Download File from URL` (or the consuming step) in a **Retry Scope** whose condition is a `File Exists` / `Path Exists` check on the **final** target path — i.e. validate the real extension is present and there is **no** `.tmp` — with a retry interval of ~5 seconds. This waits for the stream to finalize before proceeding.
+- **Gate downstream steps on the final file:** before reading the file, poll `File Exists` for the exact target name (not `*.tmp`); only continue once the finalized file is present.
+- **General:** never assume the file is ready the instant the activity returns — validate the finalized path/extension before consuming it.

package/skills/uipath-troubleshoot/references/activity-packages/file-operations/summary.md

@@ -0,0 +1,10 @@
+# File Operations Activities Playbooks
+
+**Overview:** [overview.md](./overview.md) — `UiPath.Activities.System.FileOperations` (System > File) activities in `UiPath.System.Activities`; `Download File from URL` execution model and common failure patterns
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Download File from URL — "This instance has already started one or more requests" (in a loop) | Medium | `DownloadFileFromUrl` inside a `For Each` reuses/disposes its internal HTTP client across iterations. Fix: instantiate a fresh `System.Net.Http.HttpClient` per iteration, or force release with `GC.Collect()` / `GC.WaitForPendingFinalizers()` after the download | [download-file-httpclient-reused-in-loop.md](./playbooks/download-file-httpclient-reused-in-loop.md) |
+| Download File from URL — HTTP 403 (Forbidden) / 401 (Unauthorized) | Medium | The server rejects the native download because it needs authentication / cookies / a browser session the activity doesn't carry (or a blocked `User-Agent`). Fix: set `UserAgentHeader` / authenticate, or download through a UI browser session (Click + Wait for Download) for portal-gated files | [download-file-403-401-auth.md](./playbooks/download-file-403-401-auth.md) |
+| Download File from URL — file stuck as .tmp | Medium | The activity finishes but downstream steps fail because the saved file is left as `*.tmp` (the download/finalize raced). Fix: wrap in a Retry Scope with a File Exists check validating the real target extension (not `.tmp`) | [download-file-stuck-tmp.md](./playbooks/download-file-stuck-tmp.md) |
+| Download File from URL — "Don't know about such a host" (DNS / firewall) | Medium | DNS cannot resolve the host, or an enterprise firewall / SSL-inspection proxy blocks the automated outbound connection. Fix: have the network team whitelist the endpoint for the robot/user-agent; verify connectivity from the robot host | [download-file-host-not-found.md](./playbooks/download-file-host-not-found.md) |

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

@@ -0,0 +1,36 @@
+# Intelligent OCR / Document Understanding Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Activity** — the faulted activity is a classic DU activity (`UiPath.IntelligentOCR.Activities.DigitizeDocument`, `...ClassifyDocumentScope`, `...DataExtractionScope`, `...PresentValidationStation`, `...ExportExtractionResults`). Modern DU / IXP is a different surface.
+- **Tenant / DU endpoint** — the tenant and DU endpoint/API key in evidence are the ones the user is asking about. A different tenant = different DU entitlement and a different storage layout.
+- **Storage bucket / folder** — the bucket, blob path, and Orchestrator folder named in the error are the ones the workflow targets.
+- **Document** — the document being processed is the one the user reports (matters for size-limit and validation-rejection cases).
+- **Workflow file** — the error originates from the workflow the user references.
+- **Timestamp** — the failure occurred in the reported window (load-bearing for a transient DU-server outage vs. a config problem).
+
+If the data doesn't match: discard it.
+
+## Domain-Specific Data Gathering
+
+1. **Classify by exception type and message.**
+   - `DUApiException` → the **DU server / endpoint** rejected the HTTP call. Read the HTTP status and message: 401 license/API key, 403 page-units, 413 request size, 400 wrong endpoint/API key, signature-invalid, or the generic `DocumentUnderstanding server returned <code> ...`.
+   - `Failed to fetch Document Understanding projects list...` / `Couldn't retrieve a tenant key.` / `Information about tenant <id> couldn't be retrieved.` → **tenant not enabled / setup**: DU isn't enabled/licensed on the tenant, or tenant context couldn't be resolved.
+   - `No such bucket ...` / `Couldn't find path ...` / `Could not load the ... from storage bucket ...` / `The local directory path ... could not be found.` / `Could not find Orchestrator Folder ...` → **storage / taxonomy / folder** missing.
+   - `DocumentRejectedByUserException` → a **human rejected** the document at Validation Station (a business outcome, not a system fault).
+2. **For a `DUApiException`, the HTTP status is the discriminator.** The message text is fixed per status — match it (e.g. 401 → `Your license could not be validated...`). Capture `CF-RAY` and `AppId` from the exception for escalation; the `HttpResponseContent` carries the server's detail.
+3. **Separate license from connectivity.** 401/403 are entitlement/units; a generic `DocumentUnderstanding server returned 5xx ...` is a server-side/transient failure — check the window.
+4. **For storage errors, confirm what's missing and where.** The message names the bucket / blob path / folder — confirm it exists in the tenant/folder the robot runs in and that the robot account can read it.
+
+## Testing Prerequisites
+
+> The invalid-API-key failure occurs on the OCR call itself; tenant-not-enabled / storage / document-rejected failures depend on the DU project / endpoint / storage / HITL setup. Diagnosis is evidence-based from the faulted job.
+
+1. **Activity identity** — which DU activity and its display name.
+2. **Exception type + message** — `DUApiException` (with HTTP status / `CF-RAY` / `AppId`) vs. tenant resource string vs. storage resource string vs. `DocumentRejectedByUserException`, verbatim.
+3. **DU endpoint / API key** — which endpoint the activity targets and whether the API key/license parameter is configured (do not expose the key).
+4. **Tenant entitlement** — whether Document Understanding is enabled/licensed on the tenant and has page units available.
+5. **Storage** — the bucket, blob path, and Orchestrator folder the workflow reads/writes, and whether they exist and are accessible to the robot account.
+6. **Package version** — `UiPath.IntelligentOCR.Activities` version.

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

@@ -0,0 +1,33 @@
+# Intelligent OCR / Document Understanding (Classic) Activities
+
+Activities from the `UiPath.IntelligentOCR.Activities` package — the **classic Document Understanding** framework: **Digitize Document** (`DigitizeDocument`), **Classify Document Scope** (`ClassifyDocumentScope`), **Data Extraction Scope** (`DataExtractionScope`), **Present Validation Station** (`PresentValidationStation`), **Export Extraction Results** (`ExportExtractionResults`), and the Train Classifiers/Extractors scopes. Taxonomies, classifiers, and extractors drive the digitize → classify → extract → validate → export pipeline.
+
+## How These Activities Work
+
+The pipeline combines local config (taxonomy, classifier/extractor configuration) with calls to external services:
+
+1. **Tenant / project setup.** The activities resolve the Document Understanding tenant context (project list, tenant key). If DU isn't enabled/licensed on the tenant, this fails before any document is processed.
+2. **DU server calls.** Digitization (OCR) and ML extraction/classification call a Document Understanding server / endpoint over HTTP (`DUServerCaller`). The call is authenticated with an API key / license; failures here surface as `UiPath.SmartData.Utils.DocumentUnderstandingClient.DUApiException` carrying the HTTP status, response content, `CF-RAY`, and `AppId`.
+3. **Storage access.** Taxonomy, trained models, and validated extraction results are read from / written to Orchestrator storage buckets and folders. A missing bucket / blob path / folder fails the read.
+4. **Validation Station.** `Present Validation Station` shows a human the extracted data; the human can reject the document, which raises `DocumentRejectedByUserException`.
+
+## Key Activities
+
+- **Digitize Document** (`UiPath.IntelligentOCR.Activities.DigitizeDocument`) — OCR + text/layout via a DU endpoint.
+- **Classify Document Scope** (`ClassifyDocumentScope`) — classify the document type.
+- **Data Extraction Scope** (`DataExtractionScope`) — extract fields via configured extractors.
+- **Present Validation Station** (`PresentValidationStation`) — human-in-the-loop validation.
+- **Export Extraction Results** (`ExportExtractionResults`) — emit results (e.g. DataSet).
+
+## Common Failure Patterns
+
+- **License / endpoint rejected the call** — `DUApiException`: `Your license could not be validated...`, `Failed to consume the requested number of pages...`, `You have exceeded the request size limitations...`, `The service has rejected the request. Please make sure you are using the correct endpoint...`, `Response signature is invalid. Endpoint is not supported.`, or the generic `DocumentUnderstanding server returned <code> ...`. See [du-license-or-endpoint-rejected.md](./playbooks/du-license-or-endpoint-rejected.md).
+- **DU not enabled / tenant key** — `Failed to fetch Document Understanding projects list. Please connect to a tenant that has Document Understanding enabled.`, `Couldn't retrieve a tenant key.`, `Information about tenant <id> couldn't be retrieved.`. See [du-not-enabled-or-tenant-key.md](./playbooks/du-not-enabled-or-tenant-key.md).
+- **Storage bucket / taxonomy / folder missing** — `No such bucket named '<name>'`, `Couldn't find path <p> in bucket <b> associated with '<x>'`, `The local directory path '<path>' could not be found.`, `Could not load the <x> from storage bucket <b> and path <p>`, `Could not find Orchestrator Folder '<name>'`. See [du-storage-or-taxonomy-missing.md](./playbooks/du-storage-or-taxonomy-missing.md).
+- **Document rejected at Validation Station** — `DocumentRejectedByUserException` (a human rejected the document). See [du-document-rejected.md](./playbooks/du-document-rejected.md).
+
+> The **invalid-API-key** failure occurs on the OCR call itself; **tenant-not-enabled**, **storage/taxonomy**, and **document-rejected** failures depend on the DU project / endpoint / storage / HITL setup. Diagnosis is evidence-based from the faulted job's exception text + configuration.
+
+## Package
+
+NuGet: `UiPath.IntelligentOCR.Activities` · Exceptions: `UiPath.SmartData.Utils.DocumentUnderstandingClient.DUApiException`, `UiPath.IntelligentOCR.Exceptions.DocumentRejectedByUserException`

package/skills/uipath-troubleshoot/references/activity-packages/intelligent-ocr-activities/playbooks/du-document-rejected.md

@@ -0,0 +1,32 @@
+---
+confidence: medium
+---
+
+# Document Understanding — Document rejected at Validation Station
+
+## Context
+
+`Present Validation Station` (or a Validate Classification/Extraction step) faults with `UiPath.IntelligentOCR.Exceptions.DocumentRejectedByUserException` because a human reviewer **rejected** the document instead of confirming it. This is a deliberate business outcome surfaced as an exception, not a system/configuration fault.
+
+What this looks like:
+
+- `UiPath.IntelligentOCR.Exceptions.DocumentRejectedByUserException` — raised when the validation action result is "rejected." The exception carries a `DocumentRejectionReason` (the reason the reviewer picked) and an `Attributes` dictionary; the message reflects the rejection.
+
+What can cause it:
+- **Reviewer rejected the document** — the human in Validation Station marked it rejected (e.g. wrong document type, illegible, not processable, out of scope) rather than confirming the extracted data.
+
+What to look for:
+- The exception **type is `DocumentRejectedByUserException`** — the pipeline worked; a person chose to reject. The fix is workflow handling of rejection, not a technical repair. Read `DocumentRejectionReason` to understand *why* it was rejected.
+
+> **Different cause — do not apply this playbook:**
+> - `DUApiException` / tenant / storage errors are technical failures upstream of human validation → use the [license/endpoint](./du-license-or-endpoint-rejected.md), [tenant](./du-not-enabled-or-tenant-key.md), or [storage](./du-storage-or-taxonomy-missing.md) playbooks.
+
+## Investigation
+
+1. **Confirm the exception type** is `DocumentRejectedByUserException` and read `DocumentRejectionReason` / `Attributes`.
+2. **Determine whether rejection is an expected path** for this process (some workflows route rejected documents to an exception queue / human follow-up) versus an unhandled fault.
+
+## Resolution
+
+- **If rejection is a valid business outcome:** handle `DocumentRejectedByUserException` in the workflow — catch it and route the document to the rejection path (exception queue, notification, manual handling) instead of letting the job fault. Do not treat it as a technical bug. (Apply workflow changes only with explicit user approval.)
+- **If the rejection was unexpected:** review the `DocumentRejectionReason` with the reviewer — the document content/type or the extraction quality drove the rejection; address the upstream data quality or document routing.

package/skills/uipath-troubleshoot/references/activity-packages/intelligent-ocr-activities/playbooks/du-license-or-endpoint-rejected.md

@@ -0,0 +1,63 @@
+---
+confidence: medium
+---
+
+# Document Understanding — License or endpoint rejected the call
+
+## Context
+
+A DU activity (`Digitize Document`, `Data Extraction Scope`, `Classify Document Scope`) faults when its call to the Document Understanding OCR / server endpoint is rejected. There are **two distinct error shapes** depending on which DU client made the call — match the one you see:
+
+**A. `Digitize Document` via the UiPath Document OCR engine** (the common case). The fault is a `System.AggregateException` (the OCR call runs async), and the inner message carries the DU OCR server's response verbatim. Signature for an invalid API key:
+
+```
+System.AggregateException
+Message: One or more errors occurred. (Request CorrelationId: <guid>
+Request PredictionId: <id>
+Server response: Invalid API key specified Error:UiPathOCRInvalidApiKey CF-RAY: <ray>. AppId: )
+   at UiPath.DocumentUnderstanding.Digitizer.Digitization.PageDigitizer.ApplyOcr(...)
+   at UiPath.IntelligentOCR.Activities.Digitization.DigitizeDocument.ExecuteAsync(...)
+```
+
+The `Server response:` line + `Error:UiPathOCRInvalidApiKey` is the discriminator — the configured **UiPath Document OCR `ApiKey`** is wrong/expired/empty. Related OCR-engine server errors surface the same way (`Server response: <detail> Error:<code>`).
+
+**B. `UiPath.SmartData.Utils.DocumentUnderstandingClient.DUApiException`** (SmartData/`DUServerCaller` client path — extraction/classification/tenant calls). Carries the HTTP status, response content, `CF-RAY`, `AppId`. Verbatim messages by status:
+
+- `Your license could not be validated. Please make sure that the API key parameter is correctly configured.` (HTTP **401**) — the API key / license parameter is missing, wrong, or not valid for this endpoint.
+- `Failed to consume the requested number of pages. Please check that your license key is valid and has enough units available.` (HTTP **403**) — the license is valid but out of page units / not entitled for the volume.
+- `You have exceeded the request size limitations of the currently used plan.` (HTTP **413**) — the document/request is larger than the plan allows.
+- `The service has rejected the request. Please make sure you are using the correct endpoint for the activity and that the API key parameter is correctly configured.` (HTTP **400**) — wrong endpoint for the activity, or a malformed/misconfigured API key.
+- `Response signature is invalid. Endpoint is not supported.` — the endpoint responded but isn't a supported DU endpoint.
+- `DocumentUnderstanding server returned <code> (<reason>). Additional details: <content>. CF-RAY: <cfray>. AppId: <appId>` — generic; any other non-success status (incl. 5xx — server-side / transient).
+- `Failed to parse response.` — the server response couldn't be parsed (often downstream of one of the above).
+
+What can cause it:
+- **API key / license misconfigured** (401/400) — the key parameter is empty/wrong, or doesn't match the endpoint.
+- **Out of units / not entitled** (403) — the license ran out of page units or lacks entitlement.
+- **Request too large** (413) — document exceeds the plan's size limit.
+- **Wrong / unsupported endpoint** (400 / signature-invalid) — the activity points at the wrong endpoint for its operation.
+- **Server-side / transient** (5xx generic) — the DU service had a temporary failure.
+
+What to look for:
+- For **`Digitize Document`**, the fault is a `System.AggregateException` whose message contains `Server response: ... Error:<code>` — read that server response, not the generic `One or more errors occurred.` wrapper. `Error:UiPathOCRInvalidApiKey` = bad UiPath Document OCR `ApiKey`.
+- For the **`DUApiException`** path, the connection reached the server; the **HTTP status + message** name the cause. Capture `CF-RAY` and `AppId` for escalation.
+
+> **Different cause — do not apply this playbook:**
+> - `Failed to fetch Document Understanding projects list...` / `Couldn't retrieve a tenant key.` → DU not enabled / tenant setup, before an endpoint call → use [du-not-enabled-or-tenant-key.md](./du-not-enabled-or-tenant-key.md).
+> - `No such bucket ...` / `Could not load the ... from storage bucket ...` → storage/taxonomy access → use [du-storage-or-taxonomy-missing.md](./du-storage-or-taxonomy-missing.md).
+
+## Investigation
+
+1. **Identify the error shape.** `System.AggregateException` with `Server response: ... Error:<code>` from `PageDigitizer.ApplyOcr` → the UiPath Document OCR engine (Digitize). `DUApiException` with an HTTP status → the SmartData DU client. Read the inner `Server response:` / message, not the `AggregateException` wrapper.
+2. **Map the code/status to its cause** (`UiPathOCRInvalidApiKey` = bad OCR ApiKey; 401 license/key, 403 units, 413 size, 400 endpoint/key, signature-invalid, 5xx server).
+3. **For 401/400**, capture which endpoint and API-key parameter the activity is configured with (don't expose the key value).
+4. **For 5xx / generic**, check the failure window for a transient DU-service outage.
+
+## Resolution
+
+- **If `Server response: Invalid API key specified Error:UiPathOCRInvalidApiKey` (Digitize / UiPath Document OCR):** set a valid **UiPath Document OCR `ApiKey`** (copy the tenant's Document Understanding API key from Automation Cloud → Licenses → Consumables → AI Units; re-enter it on the OCR engine). Store it as a secure asset/credential.
+- **If 401 `Your license could not be validated...` (`DUApiException`):** correct the API key / license parameter for this endpoint (re-enter the key; confirm it's valid for the targeted DU endpoint).
+- **If 403 `Failed to consume the requested number of pages...`:** top up / fix the license units, or confirm the tenant is entitled for the volume.
+- **If 413 `You have exceeded the request size limitations...`:** reduce the document/request size (split the document, lower DPI/page count) or move to a plan that allows it.
+- **If 400 `The service has rejected the request...` / `Response signature is invalid. Endpoint is not supported.`:** point the activity at the correct DU endpoint for its operation and verify the API key.
+- **If generic 5xx `DocumentUnderstanding server returned ...`:** retry transient failures; if persistent, escalate to the DU service with the `CF-RAY` and `AppId`.

package/skills/uipath-troubleshoot/references/activity-packages/intelligent-ocr-activities/playbooks/du-not-enabled-or-tenant-key.md

@@ -0,0 +1,38 @@
+---
+confidence: medium
+---
+
+# Document Understanding — Not enabled on tenant / tenant key
+
+## Context
+
+A DU activity faults while resolving the Document Understanding tenant context — listing projects or retrieving the tenant key — before processing any document. The tenant either doesn't have DU enabled/licensed, or the tenant context couldn't be resolved.
+
+What this looks like — verbatim:
+
+- `Failed to fetch Document Understanding projects list. Please connect to a tenant that has Document Understanding enabled.` — the project list couldn't be retrieved; DU is not enabled/licensed on the connected tenant (or the robot is connected to the wrong tenant).
+- `Couldn't retrieve a tenant key.` — the DU tenant key couldn't be obtained (auth/entitlement to DU not in place).
+- `Information about tenant <id> couldn't be retrieved.` — tenant metadata lookup failed.
+
+What can cause it:
+- **DU not enabled / licensed on the tenant** — the tenant has no Document Understanding entitlement, so the project list / tenant key can't be resolved.
+- **Wrong tenant** — the robot is connected to a tenant other than the one where DU is set up.
+- **Auth / entitlement gap** — the running identity can't obtain the DU tenant key.
+
+What to look for:
+- These fire at **setup / tenant resolution**, not on a per-document endpoint call. There is no HTTP status / `DUApiException` here — it's a tenant-enablement problem, not a license-key-on-endpoint problem.
+
+> **Different cause — do not apply this playbook:**
+> - `DUApiException` with an HTTP status (401/403/400/...) → the tenant resolved and an **endpoint** call was rejected → use [du-license-or-endpoint-rejected.md](./du-license-or-endpoint-rejected.md).
+> - `No such bucket ...` / `Could not find Orchestrator Folder ...` → storage/folder access → use [du-storage-or-taxonomy-missing.md](./du-storage-or-taxonomy-missing.md).
+
+## Investigation
+
+1. **Confirm the message** is the projects-list / tenant-key / tenant-info form (no HTTP status).
+2. **Identify the connected tenant** and confirm whether Document Understanding is enabled/licensed on it.
+3. **Confirm the robot is connected to the intended tenant** — not a different tenant that lacks DU.
+
+## Resolution
+
+- **If `Failed to fetch Document Understanding projects list. Please connect to a tenant that has Document Understanding enabled.`:** enable / license Document Understanding on the tenant, or connect the robot to the tenant where DU is set up.
+- **If `Couldn't retrieve a tenant key.` / `Information about tenant <id> couldn't be retrieved.`:** confirm DU entitlement and that the running identity can resolve the tenant context; re-check the tenant connection. Escalate to the DU/tenant admin if the entitlement is present but the key still can't be retrieved.

package/skills/uipath-troubleshoot/references/activity-packages/intelligent-ocr-activities/playbooks/du-storage-or-taxonomy-missing.md

@@ -0,0 +1,44 @@
+---
+confidence: medium
+---
+
+# Document Understanding — Storage bucket / taxonomy / folder missing
+
+## Context
+
+A DU activity faults reading or writing a storage location — a taxonomy, a trained model, or validated extraction results held in an Orchestrator storage bucket / folder, or a local directory. The named resource doesn't exist where the activity looked, or the robot can't access it.
+
+What this looks like — verbatim:
+
+- `No such bucket named '<name>'` — the configured storage bucket doesn't exist in the folder/tenant the robot runs in.
+- `Couldn't find path <path> in bucket <bucket> associated with '<x>'` — the blob (taxonomy/model) isn't at that path in the bucket.
+- `Could not load the <x> from storage bucket <bucket> and path <path>` — a validated-extraction / results blob couldn't be loaded from that bucket+path.
+- `The local directory path '<path>' could not be found.` — a configured local directory doesn't exist on the robot host.
+- `Could not find Orchestrator Folder '<name>'` — the Orchestrator folder the activity targets (e.g. for Action Center / storage) doesn't exist or isn't visible to the robot.
+
+What can cause it:
+- **Bucket / blob / folder doesn't exist** — never created, deleted, or created in a different folder/tenant.
+- **Out of scope for the robot** — the bucket/folder exists but the robot account / the folder the process runs in can't see it.
+- **Wrong path** — the blob path / local directory configured on the activity is wrong or relative to an unexpected root.
+- **Pipeline gap** — an upstream step that should have produced the results blob didn't, so the load can't find it.
+
+What to look for:
+- The message names the exact bucket / path / folder — that is the missing resource. These are storage-access failures, not endpoint or tenant-enablement failures.
+
+> **Different cause — do not apply this playbook:**
+> - `DUApiException` (HTTP status) → the DU endpoint call → use [du-license-or-endpoint-rejected.md](./du-license-or-endpoint-rejected.md).
+> - `Failed to fetch Document Understanding projects list...` / `Couldn't retrieve a tenant key.` → tenant not enabled → use [du-not-enabled-or-tenant-key.md](./du-not-enabled-or-tenant-key.md).
+
+## Investigation
+
+1. **Read the named resource** from the message — bucket, blob path, Orchestrator folder, or local directory.
+2. **Confirm it exists** in the tenant/folder the robot runs in (storage bucket / folder list), and that the robot account has read access.
+3. **For a results-load failure (`Could not load the ... from storage bucket ...`),** check whether the upstream step that should have written that blob actually ran and completed.
+4. **For a local-directory error,** confirm the path exists on the robot host (not just the dev machine).
+
+## Resolution
+
+- **If `No such bucket named '<name>'`:** create / correct the storage bucket in the folder the process runs in, or point the activity at the right bucket; ensure the robot account can access it.
+- **If `Couldn't find path ... in bucket ...` / `Could not load the ... from storage bucket ...`:** correct the blob path, upload the missing taxonomy/model, or fix the upstream step that should produce the results blob.
+- **If `The local directory path '<path>' could not be found.`:** create / correct the local directory on the robot host (use an absolute path that exists there).
+- **If `Could not find Orchestrator Folder '<name>'`:** correct the folder name, or create it / grant the robot account access to it.

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

@@ -0,0 +1,10 @@
+# Intelligent OCR / Document Understanding (Classic) Activities Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Intelligent OCR / Document Understanding Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Document Understanding — License or Endpoint Rejected the Call | Medium | A DU activity's HTTP call to the Document Understanding server is rejected with `UiPath.SmartData.Utils.DocumentUnderstandingClient.DUApiException` (carries HTTP status, `CF-RAY`, `AppId`): `Your license could not be validated...` (401), `Failed to consume the requested number of pages...` (403), `You have exceeded the request size limitations...` (413), `The service has rejected the request. Please make sure you are using the correct endpoint...` (400), `Response signature is invalid. Endpoint is not supported.`, or generic `DocumentUnderstanding server returned <code> ...` (5xx). | [du-license-or-endpoint-rejected.md](./playbooks/du-license-or-endpoint-rejected.md) |
+| Document Understanding — Not Enabled on Tenant / Tenant Key | Medium | A DU activity faults resolving the tenant context before processing: `Failed to fetch Document Understanding projects list. Please connect to a tenant that has Document Understanding enabled.`, `Couldn't retrieve a tenant key.`, or `Information about tenant <id> couldn't be retrieved.`. DU isn't enabled/licensed on the connected tenant, or the robot is on the wrong tenant. | [du-not-enabled-or-tenant-key.md](./playbooks/du-not-enabled-or-tenant-key.md) |
+| Document Understanding — Storage Bucket / Taxonomy / Folder Missing | Medium | A DU activity can't read/write a storage location: `No such bucket named '<name>'`, `Couldn't find path <p> in bucket <b> associated with '<x>'`, `Could not load the <x> from storage bucket <b> and path <p>`, `The local directory path '<path>' could not be found.`, or `Could not find Orchestrator Folder '<name>'`. The taxonomy/model/results blob, bucket, folder, or local directory doesn't exist where the activity looked or isn't accessible to the robot. | [du-storage-or-taxonomy-missing.md](./playbooks/du-storage-or-taxonomy-missing.md) |
+| Document Understanding — Document Rejected at Validation Station | Medium | `Present Validation Station` faults with `UiPath.IntelligentOCR.Exceptions.DocumentRejectedByUserException` because a human reviewer rejected the document (carries `DocumentRejectionReason` + `Attributes`). A business outcome surfaced as an exception — handle the rejection path in the workflow, not a technical repair. | [du-document-rejected.md](./playbooks/du-document-rejected.md) |

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

@@ -0,0 +1,34 @@
+# IPC 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.IPC.Activities.BroadcastMessage`, `UiPath.IPC.Activities.SendMessage`). The activity is the discriminator, **not** the exception FQN: `System.TimeoutException` and `System.UnauthorizedAccessException` are generic framework types — routing to this package depends on the faulted-activity label (`[Broadcast Message]`) and a `UiPath.IPC.Activities.*` stack frame, not on the `System.*` prefix.
+- **Exception class** — `System.TimeoutException` and `System.UnauthorizedAccessException` are distinct root causes with distinct fixes; do not apply one's cause to the other. `TimeoutException` = no receiver found on the channel in time (a **timing / channel-name** problem); `UnauthorizedAccessException` = the named-pipe endpoint denied the connection (a **session / user / elevation boundary** problem).
+- **Channel** — the `Channel` string in evidence matches the channel the user is asking about, and is compared **case-sensitively** against the receiver's channel. A sender and receiver on different channel names are effectively unrelated even when both look healthy.
+- **Sender / receiver pairing** — IPC always involves two sides. Confirm which process holds the `Broadcast Message` / `Send Message` (the faulted side) and which holds the `Message Receiver Trigger`. A fault on the sender with no corresponding running receiver is the core signal for the timeout case.
+- **Robot / machine / session identity** — the sender and receiver run on the **same robot, same Windows user, same session, same machine**. Evidence showing the two processes on different hosts, different robot accounts, different user sessions, or different elevation levels is the core signal for the unauthorized-access case — not transferable "healthy" data from a co-located pair.
+- **Package version** — the `UiPath.IPC.Activities` version in each project's `project.json`. A protocol/version mismatch between sender and receiver is a distinct cause from timeout/access-denied.
+- **Timestamp** — the failure occurred during the time window the user reported, and the receiver process was (or was not) alive at the broadcast instant. Load-bearing for the timeout case — a receiver that started a second too late reproduces only with the same timing.
+
+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 `Broadcast Message` / `Send Message` node from the `.xaml` to capture the literal `Channel` expression, the `Timeout` value, and the `Message` payload type. Property-panel summaries truncate; the XAML is authoritative.
+2. **Receiver existence + channel** — whether a `Message Receiver Trigger` process exists, its exact `Channel` string, and whether it was **running in parallel** and past its listener-initialization at the broadcast instant.
+3. **Launch ordering** — how and when the receiver process is started relative to the broadcast (e.g. a `Run Parallel Process` / background job launched **before** the sender broadcasts, vs launched after / not at all).
+4. **Session / user / elevation** — the Windows session, user account, and elevation level of **both** the sender and receiver processes. Attended user session vs unattended Session 0, two different robot accounts, or one elevated + one not are the access-denied signals.
+5. **Timeout value** — the literal `Timeout` (ms). `0` drops silently with no exception; a low value can expire before a legitimately-launched receiver finishes initializing.
+6. **Package version** — `UiPath.IPC.Activities` version in both the sender and receiver `project.json`, compared against each other.
+
+## Testing Prerequisites
+
+When testing hypotheses for `Broadcast Message` / `Send Message` issues, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — confirm the faulted activity is `UiPath.IPC.Activities.BroadcastMessage` / `SendMessage` and the exception class (`TimeoutException` vs `UnauthorizedAccessException`) from the job error / logs.
+2. **Receiver state** — whether a Message Receiver Trigger on the **exact same channel** was alive and listening in parallel at the broadcast instant. The user (or someone with desktop/robot access) must confirm; it cannot be inferred from the sender's log alone.
+3. **Channel match** — the sender's `Channel` string character-for-character (case-sensitive) against the receiver's. A silent mismatch presents identically to "no receiver".
+4. **Session/user/elevation parity** — for an access-denied fault, whether both processes run under the same session, user, and elevation. This is a host-level fact, not visible in job logs.
+5. **Timeout adequacy** — the configured `Timeout` versus how long the receiver takes to come up; `0` means silent-drop, low values race the receiver's startup.

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

@@ -0,0 +1,35 @@
+# IPC Activities
+
+Activities from the `UiPath.IPC.Activities` package for **inter-process communication** between UiPath processes running at the same time. One process broadcasts or sends a message on a named **channel**; another process, running a **Message Receiver Trigger** on the same channel, receives it. The transport is a local **named pipe** — communication is confined to the **same robot, same Windows user, same session, same machine**. It is not a network / cross-machine / cross-user bus.
+
+Do NOT confuse this package with the internal `UiPath.Ipc` / `UiPath.CoreIpc` transport that Integration Service connector activities use under the hood (`RemoteException`, `DAP-*` codes) — that is a different concern documented under Integration Service.
+
+## How Broadcast Message Executes
+
+`Broadcast Message` (`UiPath.IPC.Activities.BroadcastMessage`) publishes a message to every active listener on a channel. Behaviour chain:
+
+1. Open / connect to the local named-pipe endpoint for the configured `Channel` string.
+2. Search for an active **Message Receiver Trigger** listening on that exact channel, up to the `Timeout` (milliseconds).
+3. Deliver the `Message` payload to the receiver(s) found.
+
+Failures originate at distinct layers — **no receiver found within the timeout** (step 2, `System.TimeoutException`), **the pipe / session boundary denies the connection** (step 1, `System.UnauthorizedAccessException`), a **channel-string mismatch** (the receiver is up but on a different channel name — surfaces as a timeout, or silently drops when `Timeout = 0`), or a **package-version mismatch** between sender and receiver (protocol incompatibility). Knowing which layer produced the error narrows the investigation.
+
+## Key Activities
+
+- **Broadcast Message** (`BroadcastMessage`, display name "Broadcast Message") — publish a `Message` to all listeners on `Channel`, waiting up to `Timeout` ms for a receiver. Key properties: `Channel` (exact, case-sensitive string), `Message` (payload), `Timeout` (Int32 ms — `0` = drop immediately if no receiver, no exception).
+- **Send Message** (`SendMessage`, display name "Send Message") — send a `Message` to a single receiver on `Channel`, optionally awaiting a response. Same channel / timeout / session model as Broadcast Message.
+- **Message Receiver Trigger** (`MessageReceiverTrigger`, display name "Message Receiver Trigger") — the listener side. Runs in the receiver process and fires when a message arrives on its `Channel`. Must be **running in parallel** before the sender broadcasts.
+- **Get Messages** (`GetMessages`) — retrieve queued messages received on a channel.
+
+## Common Failure Patterns
+
+- **`System.TimeoutException` — no channel / receiver found** — `Broadcast Message` (or `Send Message`) faults with `Timeout of <N> ms has passed and no channel was found to send the message to.`. The activity searched for a live Message Receiver Trigger on the channel but the timeout expired first. Causes: the receiver process was **not running in parallel** (not launched, launched too late, still initializing its listener loop, or already exited), the **channel string does not match** (case-sensitive) between sender and receiver, or the `Timeout` is set **too low** for the receiver to come up. See [broadcast-message-timeout.md](./playbooks/broadcast-message-timeout.md).
+- **`System.UnauthorizedAccessException` — pipe / session boundary denies the connection** — `Broadcast Message` faults with `Access to the path is denied.` / a named-pipe access-denied while opening the channel endpoint. IPC is confined to the same robot, user, and session; the named-pipe ACL rejects a peer in a **different Windows user session**, under a **different user account**, or at a **different elevation level** (one process elevated / "Run as administrator", the other not). Causes: sender and receiver split across sessions (e.g. attended user session vs unattended Session 0), different robot accounts, or an elevation mismatch. See [broadcast-message-unauthorized-access.md](./playbooks/broadcast-message-unauthorized-access.md).
+- **Messages silently dropped (`Timeout = 0`)** — no exception, but the receiver never gets the message because `Timeout` is `0` and no listener was active at the instant of the broadcast. Trace the receiver's actual receipt, not just the absence of an exception on the sender.
+- **Package-version mismatch** — sender and receiver reference **different `UiPath.IPC.Activities` versions**, so the wire protocol is incompatible even when the channel and session match. Align the package version in both projects (Manage Packages → same version).
+
+## Package
+
+NuGet: `UiPath.IPC.Activities`
+
+Version-specific behaviour is documented in the relevant playbooks.

package/skills/uipath-troubleshoot/references/activity-packages/ipc-activities/playbooks/broadcast-message-timeout.md

@@ -0,0 +1,38 @@
+---
+confidence: medium
+---
+
+# Broadcast Message — System.TimeoutException (No Channel / Receiver Found)
+
+## Context
+
+What this looks like:
+- Activity `Broadcast Message` / `Send Message` (`UiPath.IPC.Activities.BroadcastMessage` / `SendMessage`) faults with `System.TimeoutException`
+- Message: `Timeout of <N> ms has passed and no channel was found to send the message to.`
+- May be intermittent — succeeds when the receiver is up in time, faults when it is not
+
+What can cause it:
+- The activity searches for an active **Message Receiver Trigger** listening on the configured `Channel`, up to `Timeout` (ms). The timeout expired before a live receiver was found. Root causes:
+  - **Receiver not running in parallel** — the receiver process was not launched, was launched *after* the broadcast, was still initializing its listener loop, or had already exited when the sender broadcast.
+  - **Channel-string mismatch** — the receiver is up, but its `Channel` does not match the sender's **exactly** (the comparison is case-sensitive). To the sender this is indistinguishable from "no receiver".
+  - **`Timeout` too low** — the receiver comes up legitimately but slower than the configured window, so the search expires first.
+
+What to look for:
+- Whether a Message Receiver Trigger process on the **same channel** was alive and past initialization at the broadcast instant.
+- The sender's `Channel` string vs the receiver's, character-for-character (case-sensitive).
+- The launch ordering — is the receiver started **before** the broadcast?
+
+## Investigation
+
+1. Confirm the faulted activity is `Broadcast Message` / `Send Message` and the exception is `System.TimeoutException` with the `no channel was found` message; capture `<N>` (the configured `Timeout`).
+2. Read the sender `.xaml` for the literal `Channel` string and `Timeout` value.
+3. Ask the user (or someone with robot access) whether the receiver process (Message Receiver Trigger) was running in parallel on the **exact same channel** at the broadcast time, and how/when it is launched relative to the sender.
+
+## Resolution
+
+- **Launch the receiver in parallel first** — start the Message Receiver Trigger process **before** the sender broadcasts, e.g. via a `Run Parallel Process` activity or a background job, and confirm its listener is initialized. IPC requires the receiver to be actively listening at the moment of the broadcast.
+- **Match the channel string exactly** — verify both sides use the identical, case-sensitive `Channel` value (prefer a shared config asset / constant over hand-typed literals to avoid `OrderBus` vs `orderbus` drift).
+- **Raise the `Timeout`** — set `Timeout` to at least **5000–10000 ms** so the receiver has time to initialize its listener loop before the search expires. Do not set it too low. (`Timeout = 0` drops the message immediately with **no** exception — a different, silent failure mode.)
+- **Wrap in Try Catch** — if a receiver may legitimately be absent, wrap `Broadcast Message` in a Try Catch to handle the `TimeoutException` gracefully rather than faulting the job.
+
+> Related: a receiver that IS up on the same channel but the pipe endpoint denies the connection (different session / user / elevation) throws `System.UnauthorizedAccessException`, not a timeout → [broadcast-message-unauthorized-access.md](./broadcast-message-unauthorized-access.md).

package/skills/uipath-troubleshoot/references/activity-packages/ipc-activities/playbooks/broadcast-message-unauthorized-access.md

@@ -0,0 +1,38 @@
+---
+confidence: medium
+---
+
+# Broadcast Message — System.UnauthorizedAccessException (Pipe / Session Boundary)
+
+## Context
+
+What this looks like:
+- Activity `Broadcast Message` / `Send Message` (`UiPath.IPC.Activities.BroadcastMessage` / `SendMessage`) faults with `System.UnauthorizedAccessException`
+- Message: `Access to the path is denied.` (or a named-pipe access-denied while opening the channel endpoint)
+- Often reproduces **consistently** for a given deployment topology (unlike the timing-dependent timeout case)
+
+What can cause it:
+- IPC runs over a **local named pipe** confined to the **same robot, same Windows user, same session, same machine**. The pipe's ACL rejects a peer that lives across a boundary:
+  - **Different Windows user session** — sender and receiver split across sessions (e.g. an attended user session on one side, an unattended **Session 0** robot on the other).
+  - **Different user account** — the two processes run under different robot / Windows accounts, so neither can open the other's session-scoped pipe.
+  - **Elevation mismatch** — one process runs **elevated** ("Run as administrator" / high integrity) and the other does not; the integrity-level boundary denies the connection.
+
+What to look for:
+- The Windows session, user account, and elevation level of **both** the sender and receiver processes.
+- Whether the deployment split the two processes across attended vs unattended, or across two robot accounts.
+- That this is a boundary/permission fault, not a timing fault — the receiver may be perfectly alive on the right channel.
+
+## Investigation
+
+1. Confirm the faulted activity is `Broadcast Message` / `Send Message` and the exception is `System.UnauthorizedAccessException` (access-denied on the channel endpoint) — not `TimeoutException`.
+2. Establish where the receiver process runs: which robot / Windows user, which session, and at what elevation, versus the sender.
+3. Ask the user (or someone with robot/host access) to confirm both processes are intended to run on the **same** robot, user, session, and elevation — this is a host-level fact not visible in the sender's job log.
+
+## Resolution
+
+- **Co-locate both processes** — run the sender and receiver on the **same robot, same Windows user, same session, same machine**. `UiPath.IPC.Activities` does **not** support communication across machines or across Windows user sessions.
+- **Match elevation** — ensure both processes run at the **same integrity level**: either both elevated or both non-elevated. A single elevated peer will be denied by the other's pipe ACL.
+- **Align the robot account** — if the two processes run under different robot accounts, reconfigure so they execute under the **same** account in the same session (e.g. both as the same unattended robot, launched via `Run Parallel Process` so they share the session).
+- **Do not treat as a timeout** — raising `Timeout` will not fix an access-denied fault; the connection is refused at the pipe, not lost to timing.
+
+> Related: a receiver that is simply absent / on a mismatched channel / not up in time throws `System.TimeoutException` instead → [broadcast-message-timeout.md](./broadcast-message-timeout.md).

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

@@ -0,0 +1,9 @@
+# IPC Activities Presentation Rules
+
+- **Activities** — use the display name (e.g., "Broadcast Message", "Send Message", "Message Receiver Trigger"), not the fully qualified class name (e.g., `UiPath.IPC.Activities.BroadcastMessage`)
+- **Channels** — quote the `Channel` string exactly as configured, in backticks, and flag case sensitivity when a mismatch is suspected (e.g. "sender channel `OrderBus` vs receiver channel `orderbus`")
+- **Sender / receiver** — always name which side you mean: the **sender** (the process holding `Broadcast Message` / `Send Message`) and the **receiver** (the process holding the `Message Receiver Trigger`). Never say just "the process" when both are in play
+- **Exceptions** — quote the exact exception class and message together (e.g. "`System.TimeoutException`: `Timeout of 3000 ms has passed and no channel was found to send the message to.`"), and state which layer it maps to (no-receiver-in-time vs pipe-ACL-denied)
+- **Timeout** — refer to the `Timeout` property in milliseconds and state the practical floor (5000–10000 ms) when recommending a raise; call out `Timeout = 0` explicitly as the silent-drop setting
+- **Run surface** — name the session/user in the user's terms (e.g. "attended user session", "unattended robot (Session 0)", "elevated / Run as administrator") so the user can check the boundary, not internal runtime flags
+- **Launch mechanism** — name the concrete mechanism the user configures (e.g. "`Run Parallel Process`", "a background job started before the broadcast"), not an abstract "run it in parallel"

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

@@ -0,0 +1,9 @@
+# IPC Activities Playbooks
+
+**Overview:** [overview.md](./overview.md) — `UiPath.IPC.Activities` package, channel / named-pipe execution model, and common failure patterns
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for IPC Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Broadcast Message — `System.TimeoutException` (no channel / receiver found) | Medium | `Broadcast Message` / `Send Message` faults with `Timeout of <N> ms has passed and no channel was found to send the message to.` — no live Message Receiver Trigger was found on the channel before the `Timeout` expired. Causes: the receiver process was not running in parallel (not launched, launched too late, still initializing, or exited), the `Channel` string does not match (case-sensitive) between sender and receiver, or `Timeout` is too low for the receiver to come up. Fix: launch the receiver in parallel first, match the channel string exactly, raise `Timeout` (5000–10000 ms) | [broadcast-message-timeout.md](./playbooks/broadcast-message-timeout.md) |
+| Broadcast Message — `System.UnauthorizedAccessException` (pipe / session boundary) | Medium | `Broadcast Message` / `Send Message` faults with `Access to the path is denied.` / a named-pipe access-denied on the channel endpoint. IPC is confined to the same robot, user, and session; the pipe ACL rejects a peer in a different Windows user session, under a different user account, or at a different elevation level (one process elevated, the other not). Fix: run both processes on the same robot / user / session / elevation | [broadcast-message-unauthorized-access.md](./playbooks/broadcast-message-unauthorized-access.md) |

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

@@ -0,0 +1,31 @@
+# Jira 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 (e.g., `UiPath.Jira.Activities.JiraApplicationScope` / "Jira Scope", or a child activity like "Get Issue" / "Search Issues"). A fault **at scope open** (authentication) and a fault **on a child activity** (a bad response, a failed query) are different code paths — treat them as different.
+- **Error string** — `Authentication information is invalid`, `Response was not recognized as JSON`, an HTTP `5xx`, and `This activity is either missing or could not be loaded properly` map to different playbooks. Read the literal message, not a paraphrase.
+- **Jira instance identity** — the `Server URL` in the workflow matches the instance the user reports, and whether it is Jira **Cloud** (`https://<domain>.atlassian.net`) or an on-premises **Server / Data Center** host. The classic pack targets Cloud; the deployment type is load-bearing for the not-JSON / `500` family.
+- **Authentication configuration** — the `Authentication Type` (`Api Token` / `Basic` / `OAuth 2.0`) and which credential properties are populated. A credential rejection is interpreted differently depending on which auth mode is configured and whether stray properties from another mode are still set.
+- **Account / org policy** — whether the Atlassian org enforces MFA/SSO. Load-bearing for the password-vs-API-token sub-case: basic password auth fails under enforced MFA even with correct credentials.
+- **Package + project dependencies** — the `UiPath.Jira.Activities` version from `project.json` and the other packages in the project (anything that also pins **RestSharp** or other shared transitive libraries). Load-bearing for the activity-load family.
+- **Timestamp** — the failure occurred during the time window the user reported.
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## Testing Prerequisites
+
+When testing hypotheses for `Jira Scope` failures, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — confirm the faulted activity (`Jira Scope` vs a specific child) and the exact error string. Scope-open authentication faults, child-activity response faults, and activity-load faults are different families.
+2. **Scope configuration** — from the `.xaml`, capture `Server URL`, `Authentication Type`, `Username`, and which credential properties (`Api Token`, `Password`, `Client Id`, `Client Secret`) are set. Note the **data type** bound to `Api Token` / `Password` (must be `SecureString`, not `String`).
+3. **Username format** — whether `Username` is the account **email** (Cloud requirement) or an alphanumeric `accountId`.
+4. **Server URL shape** — whether `Server URL` is the bare root instance (`https://<domain>.atlassian.net`) or has a path appended (`/secure/Dashboard.jspa`, a project key, a `/browse/...` link).
+5. **Deployment type** — Jira Cloud vs on-premises Server / Data Center. Not always in the job log; the `Server URL` host and the user confirm it.
+6. **Org auth policy** — whether MFA/SSO is enforced for the account. Determines whether basic password auth can ever succeed. Confirmed by the user / Atlassian org admin, not the job log.
+7. **Project dependency set** — `UiPath.Jira.Activities` version and any sibling package that pins a conflicting **RestSharp** (or other shared assembly). Read from `project.json` and, when available, the build/restore log.
+
+### Out-of-band confirmation
+
+Two deciding proofs for Jira causes live outside the job log: whether the Atlassian org **enforces MFA/SSO** (org admin / Atlassian account settings), and whether a freshly generated **API token** authenticates the same `Server URL` (the user regenerates a token at *Atlassian Account → Security → API tokens* and retries). Record these as out-of-band confirmation steps — they do not block a hypothesis when no alternative cause is better supported, but they are how the user closes the case.