@uipath/skills 1.196.0 → 1.197.0

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

@@ -8,4 +8,18 @@
 | Item Name Already Exists | High | Destination already contains an item with the target name and `ConflictBehavior = Fail` (`Office365Exception: The specified item name already exists.`). Raised by Files (`CreateFolderConnections`, `CopyItemConnections`, `MoveItemConnections`, `RenameItemConnections`, `UploadFilesConnections`), Excel (`CreateWorkbookConnections`, `AddSheetConnections`, `RenameSheetConnections`), and legacy activities equivalents. Conflict is on the OneDrive/SharePoint/Excel side. | [item-name-already-exists.md](./playbooks/item-name-already-exists.md) |
 | Download — Multiple Items Name Conflict | High | Download activity (`DownloadEmailConnections`, `DownloadFileConnections`, `DownloadEmailAttachments`) throws `Office365Exception: Multiple items with the name <name> found in the specified folder.` because the **local** destination folder already contains a file with that name and `ConflictResolution = Fail`, or two attachments on the same email resolve to the same local filename. | [download-multiple-items-name-conflict.md](./playbooks/download-multiple-items-name-conflict.md) |
 | Mail — Folder Not Found | High | Mail activity (`MoveEmailConnections`, `GetNewestEmail`, `GetEmailListConnections`, `ForEachEmailConnections`, `WaitForEmailReceived`, `NewEmailReceived` trigger, legacy `MoveMail`) cannot resolve the configured `MailFolder`. Surfaces as `Office365Exception: The resource could not be found.`, `Folder named '<name>' could not be found on this account.`, or `Cannot find item configured with connection <connection> at path <folder>.`. | [mail-folder-not-found.md](./playbooks/mail-folder-not-found.md) |
-| Drive — File or Folder Not Found | High | OneDrive/SharePoint Drive activity (`GetFileFolderConnections`, `GetFileFolderMetadataConnections`, `GetFileListConnections`, `DownloadFileConnections`, `MoveItemConnections`, `CopyItemConnections`, `RenameItemConnections`, `DeleteItemConnections`, `ShareItemConnections`, `UpdateFileFolderMetadataConnections`, `CreateFolderConnections`, `UploadFilesConnections`, `ForEachFileFolderConnections`, `CheckinCheckoutFileConnections`, `AssignSensitivityLabelConnections`, `GetSensitivityLabelsConnections`, persistence `WaitForFile*`, legacy activities equivalents) cannot resolve the configured item. Surfaces as `Office365Exception: The resource could not be found.` or as the wrapping form `Cannot find item configured with connection <connection> at path <path>.` | [drive-item-not-found.md](./playbooks/drive-item-not-found.md) |
+| Drive — File or Folder Not Found | High | OneDrive/SharePoint Drive activity (`GetFileFolderConnections`, `GetFileFolderMetadataConnections`, `GetFileListConnections`, `DownloadFileConnections`, `MoveItemConnections`, `CopyItemConnections`, `RenameItemConnections`, `DeleteItemConnections`, `ShareItemConnections`, `UpdateFileFolderMetadataConnections`, `CreateFolderConnections`, `UploadFilesConnections`, `ForEachFileFolderConnections`, `CheckinCheckoutFileConnections`, `AssignSensitivityLabelConnections`, `GetSensitivityLabelsConnections`, persistence `WaitForFile*`, legacy `FindFilesAndFolders`, `ForEachFileFolder`, `CopyItem`, `UploadFile`, `DownloadFile`, `ExportAsPdf`, `GetItem`, `MoveItem`, `DeleteItem`, `ShareItem`, `CreateFolder`) cannot resolve the configured item. Surfaces as `Office365Exception: The resource could not be found.`, the wrapping form `Cannot find item configured with connection <connection> at path <path>.`, or on legacy activities a raw `Microsoft.Graph.ServiceException` with `Code: itemNotFound` and the same sentence. | [drive-item-not-found.md](./playbooks/drive-item-not-found.md) |
+| Insufficient Graph Scope / Access Denied (403) | High | Authenticated caller lacks the Microsoft Graph permission for the operation. Surfaces as `The caller doesn't have permission to perform the action.`, `Access restricted to the item's owner.`, or a raw `Insufficient privileges to complete the operation.` Common on write/share ops (`SendMailConnections` → Mail.Send; `ShareItemConnections`, `UploadFilesConnections`, `MoveItemConnections` → Files.ReadWrite.All / Sites.ReadWrite.All). Distinct from 404 not-found — Graph may return 404 instead of 403 for unauthorized cross-mailbox/shared access. | [insufficient-graph-scope.md](./playbooks/insufficient-graph-scope.md) |
+| Throttling / Rate Limit (429) | High | Microsoft Graph rate-limited the tenant/app/mailbox after the Graph SDK's `Retry-After` retries were exhausted. Surfaces as `Too many requests.`, `The app or user has been throttled.`, or `(HTTP Status Code: TooManyRequests) Batching request failed with an unknown reason.` Most likely under high call volume — `ForEachFileFolderConnections`, `ForEachEmailConnections`, `BulkAddListItemsConnections`, retrieve-all reads (`MaxResults = 0`), or batching. No resource to fix — resolved by backoff / lowering the call rate. (On package 3.9.11 the SDK "retries exhausted" case surfaces raw, not as `Too many requests.` — see the playbook.) | [request-throttled.md](./playbooks/request-throttled.md) |
+| Authentication / Token Invalid (401) | Medium | Any Mail/Files/Excel activity faults at authentication: a raw token message (e.g. `Access token has expired or is not yet valid.`), `The caller is not authenticated.`, an `AADSTS<code>` configuration error (consent / credentials), an interactive-login timeout, `No default connection is available.`, or `Automation Cloud cannot be reached...`. Expired/invalid token, revoked/missing consent, cancelled interactive login, or missing/unauthenticated connection. | [authentication-token-invalid.md](./playbooks/authentication-token-invalid.md) |
+| Transient Service Error / Timeout (5xx) | Medium | Server/transport-side failure, generally not user-correctable: `The server is unable to process the current request.` (503), `Request time out.`, a raw 500/504/timeout inner message, the Mail `... modify your Query or Top values ...` 500, a batched 5xx, or `Automation Cloud cannot be reached...`. Resolved by retry with backoff. Distinct from 429 throttling. | [transient-service-error.md](./playbooks/transient-service-error.md) |
+| Mail — Message Not Found | High | Message-by-ID Mail operation (`GetEmailByIdConnections`, `ForwardEmailConnections`, `ReplyToEmailConnections`, `MarkAsReadUnreadConnections`, `DeleteEmailConnections`, `ArchiveEmailConnections`, `DownloadEmail*`, legacy `ForwardMail`/`ReplyToMail`/`DeleteMail`/`SetMailCategories`/`GetMail` with `EmailId`, `NewEmailReceived` by-ID fetch) cannot resolve the message. Surfaces as `The resource could not be found.`, raw `ErrorItemNotFound` (`The specified object was not found in the store.`), `ErrorInvalidMailboxItemId` (`Item ... doesn't belong to the targeted mailbox`), or `ErrorInvalidIdMalformed` (`Id is malformed.` — corrupted/truncated stored ID; Outlook IDs are integrity-checked). Message deleted/moved, mailbox-scoped ID used against another mailbox, or stale/corrupted persisted ID. | [mail-message-not-found.md](./playbooks/mail-message-not-found.md) |
+| Mail — Invalid OData Query | High | Mail read (`GetMail`, `GetNewestEmail`, `GetEmailListConnections`, `ForEachEmailConnections`, filter-based triggers) faults with `Invalid Query. Please use OData format for filter queries. Press F1 for examples.` (fixed text, both legacy and Connections) or a raw Graph invalid-filter message. Malformed `$filter` syntax, wrong property names, or bad literal formats. Deterministic — fixed by correcting the query. | [mail-invalid-odata-query.md](./playbooks/mail-invalid-odata-query.md) |
+| Mail — Send / Forward / Reply Rejected | Medium | Send-path fault on the message itself: `File does not exist: <path>` (missing attachment), or raw Graph rejections matched by code family — `ErrorInvalidRecipients`, `ErrorSendAsDenied` (shared mailbox without Exchange Send As), `ErrorMessageSizeExceeded`. `SendMailConnections`, legacy `SendMail`, `ForwardMail`/`ForwardEmailConnections`, `ReplyTo*`. | [send-mail-rejected.md](./playbooks/send-mail-rejected.md) |
+| Email Trigger — Connection Event Failure | Medium | `NewEmailReceived`/`EmailSent` trigger faults at the Integration Service connection layer — raw `UiPath.ConnectionClient.Contracts.ConnectionHttpException` or `Office365Exception` carrying the identical message (HTTP status embedded) — while fetching the event email, debug sample, or connection token. Connection deleted/unauthorized/not in folder, or IS-side 5xx. | [email-trigger-connection-event-failure.md](./playbooks/email-trigger-connection-event-failure.md) |
+| Legacy Mail — NullReferenceException | Medium | Raw `System.NullReferenceException` from legacy `SendMail`/`ForwardMail`/`ReplyToMail` — null `Message` input or null element in `To`/`Cc`/`Bcc` arrays. Raw NRE type always indicates a legacy activity (Connections path remaps it to `The object used in the activity does not exist.`). | [legacy-mail-null-reference.md](./playbooks/legacy-mail-null-reference.md) |
+| Copy Item — Null DriveItem | High | Legacy `CopyItem` throws raw `ArgumentNullException: Value cannot be null. (Parameter 'DriveItem')` — the bound variable is null because an upstream `FindFilesAndFolders`/get-item matched nothing. Null parent is legal (OneDrive root fallback); only `DriveItem` faults. | [copy-item-argument-null.md](./playbooks/copy-item-argument-null.md) |
+| Create Folder — Invalid Name or Path | High | `CreateFolderConnections` input errors: `Value cannot be null. (Parameter 'Folder name'/'Folder path'/'Parent folder')`, `Folder path must contain at least one segment.`, `Folder path segment '<segment>' cannot have leading or trailing whitespace.`, or `Cannot create folder path: '<segment>' is a file, not a folder.` | [create-folder-invalid-path.md](./playbooks/create-folder-invalid-path.md) |
+| Download — Conversion or Destination Error | High | `DownloadFileConnections` / legacy `DownloadFile`/`ExportAsPdf`: `Folders cannot be downloaded with this activity. ...`, unsupported PDF source extension, non-`.pdf` destination (`Local File Path should point to a folder or directly to a .pdf file.`), empty filename, or shared-item parent unresolvable (`Cannot locate file. Please ensure that you have proper permissions to access it.`). | [download-file-conversion-or-destination.md](./playbooks/download-file-conversion-or-destination.md) |
+| Upload — Quota, Size, or Session Failure | Medium | `UploadFilesConnections` / legacy `UploadFile`: `The user has reached their quota limit.` (storage full — NOT throttling), `Max file size exceeded.` / `Maximum stream size exceeded.`, or `Upload session failed/incomplete/not found.` (transient chunked-upload break). Raw Graph wording on legacy. | [upload-file-quota-or-size.md](./playbooks/upload-file-quota-or-size.md) |
+| Application Scope / Connection Misconfiguration | Medium | Faults **before any Graph call**, from the Microsoft 365 Application Scope's own configuration: `Could not retrieve the selected asset: ...`, `You must provide a literal value for <field> ...`, `The authentication parameters could not be read`, `You must provide a value for <field>`, `Please select an account.`, or placement errors (`Activity is only valid inside an Office 365 Scope` / `Cannot be used outside of a MicrosoftOffice365 Application Scope or outside of a Use OneDrive/SharePoint activity`). Fixed in Studio / Orchestrator configuration. | [application-scope-misconfigured.md](./playbooks/application-scope-misconfigured.md) |

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

@@ -0,0 +1,32 @@
+# Python 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.Python.Activities.InvokeMethod` / "Invoke Python Method", `UiPath.Python.Activities.PythonScope` / "Python Scope", `UiPath.Python.Activities.RunScript` / "Run Python Script"). A `Pipe is broken` fault at `Invoke Python Method` and an interpreter-resolution fault at `Python Scope` are different code paths — treat them as different.
+- **Python script** — the `.py` file (or inline code) in evidence matches the script the user is asking about. `Load Python Script` / `Run Python Script` reference a specific `File`; a different script is unrelated data.
+- **Interpreter identity** — the Python install the scope's `Path` / `Version` / `Target` resolves to matches the interpreter the user reports. The packages available at runtime are those installed in **that** interpreter, not the developer's IDE environment and not a different Python on the same host.
+- **Robot / machine identity** — the robot account and the machine where Python is installed match the one the user reports. Python interop is per-machine and per-interpreter; evidence from the developer's machine (where "it runs fine") is not transferable to the robot host.
+- **Run surface** — whether the run was foreground Studio / attended or unattended / Session 0 / background. Load-bearing for `WorkingFolder` / relative-path causes (the robot's CWD differs from Studio's) and for interpreter access (the robot user may not see a per-user Python install).
+- **Package + runtime version** — the `UiPath.Python.Activities` version from `project.json`, the interpreter version, and the installed .NET Desktop Runtime. The pack supports a specific Python-version / runtime matrix; a skew here produces engine-init failures unrelated to the user's code.
+- **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 `Python Scope` failures, gather and verify these before drawing conclusions:
+
+1. **Activity identity** — confirm the faulted activity (`Python Scope`, `Load Python Script`, `Run Python Script`, `Invoke Python Method`, `Get Python Object`) and the exact error string. `Pipe is broken`, `The specified Python path is not valid`, and `One or more errors occurred` / `Error initializing the Python engine` map to different playbooks.
+2. **Scope configuration** — from the `.xaml`, capture the `Python Scope` `Path`, `Library path`, `Version`, `Target`, and `WorkingFolder`. Check `Path` for the two classic traps: ending in `\python.exe`, or pointing at `...\WindowsApps\python`.
+3. **Script source** — read the `.py` file(s) referenced by `Load Python Script` / `Run Python Script`. Note every `import` (third-party modules are the prime `Pipe is broken` suspect), any top-level `sys.exit` / `os._exit`, heavy stdout/print volume, and any relative file path the script opens.
+4. **Interpreter packages** — whether the third-party modules the script imports are installed in the interpreter the scope's `Path` resolves to (not the dev's IDE). Not visible in the job log — the user (or someone with access to the robot host) confirms via `<scope-path>\python.exe -m pip list`.
+5. **Interpreter bitness / version** — the actual install's bitness (x86 / x64) and version vs the scope's `Target` / `Version`. Run-surface dependent: a per-user install under the developer's profile may not exist for the robot user.
+6. **Run surface** — foreground Studio Run/Debug vs attended vs unattended / Session 0. Confirms or eliminates the `WorkingFolder` CWD-divergence cause and per-user-interpreter visibility.
+7. **Package + .NET runtime version** — `UiPath.Python.Activities` version from `project.json` and the installed .NET Desktop Runtime, checked against the pack's supported matrix.
+8. **Load vs invoke isolation** — confirm whether the failure is at load (`Load Python Script` — engine init or script import; the scope/script never bound) or at invocation (`Invoke Python Method` — the script loaded and the failure is in the called function). They have different root causes and fixes; an engine-init / load fault surfacing under an invoke routes to [load-script-failures.md](./playbooks/load-script-failures.md).
+
+### Out-of-band confirmation
+
+The deciding proof for several Python causes lives on the robot host, not in the job log: whether the imported module is installed in the scope's interpreter (`pip list`), the interpreter's true bitness, and whether the script runs standalone from that exact interpreter (`<scope-path>\python.exe <script>`). 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.

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

@@ -0,0 +1,38 @@
+# Python Activities
+
+Activities from the `UiPath.Python.Activities` package for invoking Python from a UiPath workflow on Windows or cross-platform. The package does **not** run Python in-process. `Python Scope` spawns a separate Python host process (a child `python.exe` / interpreter) and marshals objects to and from it over an IPC pipe. Child activities — `Load Python Script`, `Run Python Script`, `Invoke Python Method`, `Get Python Object` — call into that out-of-process host across the pipe.
+
+## How Python Scope Executes
+
+`Python Scope` resolves an interpreter from its properties, launches it as a child process, and exposes the live host to child activities:
+
+1. Resolve the interpreter from `Path` (the install **folder**), `Version`, `Target` (bitness), and — for Python > 3.9 on Windows / any Linux — `Library path` (the `pythonXY.dll` / `libpythonX.Y.so`).
+2. Spawn the Python host process and open the IPC pipe to it.
+3. `Load Python Script` / `Run Python Script` send code into the host; `Invoke Python Method` calls a function; `Get Python Object` marshals a `PythonObject` back to a .NET type.
+4. Close the host and the pipe at end of scope.
+
+Two properties of this model drive most failures:
+
+- **The interpreter is external and resolved from the scope, not from the developer's machine state.** `Path` must point at the install folder (never at `python.exe` itself, never at the `WindowsApps\python` Store alias). `Target` (x86 / x64) and `Version` must match the actual interpreter on the **robot** host, not the developer's. A mismatch fails before any script runs.
+- **The Python side is a black box reached over a pipe.** Any unhandled Python-side failure — `ModuleNotFoundError`, a syntax error, a non-zero `sys.exit`, an OOM kill, flooding stdout — kills the host process and breaks the pipe. UiPath surfaces this as a generic `Pipe is broken`, not the underlying Python traceback. The packages installed in the **scope's** interpreter (not the dev's IDE) are what's available at runtime.
+
+## Key Activities
+
+- **Python Scope** (`UiPath.Python.Activities.PythonScope`) — resolve and launch the interpreter; host all child Python activities. Properties: `Path` (install folder), `Library path` (the `.dll`/`.so`, > 3.9 / Linux only), `Version` (`Auto` or e.g. `Python_311`), `Target` (`x86` / `x64`), `WorkingFolder`, `Timeout`.
+- **Load Python Script** (`UiPath.Python.Activities.LoadScript`) — load code from a file or string into a `PythonObject`. Properties: `File` / `Code`, `Result`.
+- **Run Python Script** (`UiPath.Python.Activities.RunScript`) — load and execute a script in one step.
+- **Invoke Python Method** (`UiPath.Python.Activities.InvokeMethod`) — call a function in a loaded `PythonObject`. Properties: `Instance`, `Name`, `InputParameters`, `Result`.
+- **Get Python Object** (`UiPath.Python.Activities.GetObject`) — marshal a `PythonObject` to a .NET type. Properties: `PythonObject`, `TypeArgument`, `Result`.
+
+## Common Failure Patterns
+
+- **`Pipe is broken` / `Error invoking Python method`** — the child Python host process died or stopped responding (commonly raised at `Invoke Python Method` / `Run Python Script`, often wrapped as `RemoteException wrapping System.IO.IOException: Pipe is broken`). The Python-side cause is hidden: a missing pip module in the scope's interpreter, an unhandled exception, a hard `sys.exit`, or flooding stdout. The script "runs fine in my IDE" because the IDE uses a different interpreter with the module installed.
+- **`The specified Python path is not valid: <path>`** — `Python Scope` could not resolve the interpreter from `Path`. Usual traps: `Path` points at `python.exe` (the executable) instead of the **folder** containing it, or at the `%LocalAppData%\Microsoft\WindowsApps\python` Microsoft Store alias (not a real install).
+- **`One or more errors occurred` / `Error initializing the Python engine`** — interpreter could not be loaded. Bitness mismatch (`Target` x86 vs a 64-bit install, or vice-versa), a `Version`/`Library path` that doesn't match the install, or a missing .NET Desktop Runtime the engine depends on.
+- **Script runs but reads/writes the wrong files** — relative paths inside the script resolve against `WorkingFolder`, which defaults to the robot's per-package directory, not the project folder. Same CWD-divergence class as relative workflow paths.
+
+## Package
+
+NuGet: `UiPath.Python.Activities`
+
+Version-specific behavior is documented in the relevant playbooks. The pack pins which Python versions and runtimes a given release supports (and the required .NET Desktop Runtime) — match the package version to the interpreter and runtime on the **robot** host before concluding a code defect. See the [package documentation](https://docs.uipath.com/activities/other/latest/developer/about-the-python-activities-pack) for the supported-version matrix.

package/skills/uipath-troubleshoot/references/activity-packages/python-activities/playbooks/invoke-method-failures.md

@@ -0,0 +1,57 @@
+---
+confidence: medium
+---
+
+# Invoke Python Method (InvokeMethod) Failures
+
+## Context
+
+`UiPath.Python.Activities.InvokeMethod` ("Invoke Python Method") runs **after** `Load Python Script` inside a `Python Scope`. It takes the `PythonObject` from `LoadScript` as its `Instance`, calls the function named in `Name` with the arguments in `InputParameters`, and returns a `PythonObject` in `Result` (typically converted by `Get Python Object`). A failure here means the engine initialized and the script loaded — the fault is in **resolving or calling the function**, in the **arguments**, or in **Python code that runs inside the function**.
+
+If the failure is actually at engine init or script load (`Error initializing Python engine`, `The specified Python path is not valid`, `ModuleNotFoundError` from a top-level import, syntax error), it belongs to [load-script-failures.md](./load-script-failures.md), not here — `Invoke Python Method` never ran.
+
+What this looks like:
+- `One or more errors occurred` / `Error invoking the python method` (generic wrapper around a Python-side exception).
+- A Python `AttributeError` / "object has no attribute '<name>'" — the function name did not resolve.
+- A Python `TypeError` about argument count ("takes N positional arguments but M were given" / "missing required positional argument").
+- A **design-time** compile error on the `InputParameters` field (`BC36754` in VB, a type-conversion error like `CS1503`/`CS0029` in C#).
+- `System.IO.PipeException` / "Pipe is broken" mid-call.
+- `NullReferenceException` when `Instance` is empty.
+
+## Causes
+
+Name the confirmed sub-cause exactly. Do NOT assert a cause unless the investigation arrived at it.
+
+- **M1. Function name does not resolve.** `Name` does not match a function bound at the script's module level. Python raises `AttributeError` / "has no attribute". Sub-causes: a typo; **case mismatch** (`Name` is case-sensitive and must mirror the `def` exactly); the function is nested inside a class or another function (only module-level `def`s are callable by name); or the function is defined only under `if __name__ == "__main__":`, so `LoadScript` never bound it.
+- **M2. Argument mismatch at runtime.** The `InputParameters` count, order, or types do not match the function signature → Python `TypeError`. Also covers passing a **complex .NET object** (e.g. `DataTable`, a custom class) that Python cannot consume — only primitives/strings marshal cleanly across the boundary; serialize to a string/JSON or pass a file path instead.
+- **M3. `InputParameters` is not an Object array (design-time).** The field expects `IEnumerable<Object>`. Passing a raw typed array or a bare scalar fails to compile in the designer — `BC36754` ("'Integer()' cannot be converted...") in VB, or a `CS1503`/`CS0029` conversion error in C#. This is a configuration error, not a runtime fault.
+- **M4. Python-side exception inside the function.** The function resolved and was called, but its body raised — surfaces wrapped in `One or more errors occurred`. Common triggers: a **relative file path** (`open("data.csv")`) resolved against UiPath's working directory (the robot project / `WorkingFolder`), not the script's folder; a `KeyError` / `IndexError` / `ValueError` on the input; or a **lazy `import`** of a package missing from the interpreter at the scope's `Path` (a top-level import would have failed earlier in `LoadScript` — see [load-script-failures.md](./load-script-failures.md) **L2a**).
+- **M5. Broken pipe / oversized payload.** `System.IO.PipeException` ("Pipe is broken"). The return value handed back to UiPath is too large (return a file path or a boolean and write the data to a `.csv`/`.xlsx` in the script instead), the payload exceeds the scope's **Script Data Size Limit** (25 MB default), or the engine became unstable — a bitness mismatch can drop the pipe, though that usually fails earlier at engine init (see [load-script-failures.md](./load-script-failures.md) **L1b**).
+- **M6. `Instance` is null / not a loaded script.** `Instance` is not bound to a successful `LoadScript` result (the `LoadScript` faulted, was skipped, or its `Result` variable is uninitialized) → `NullReferenceException`. The real fault is upstream at load.
+
+## Investigation
+
+1. **Read the activity + script from the `.xaml`.** Capture `Instance` (which `LoadScript` result it binds), `Name`, the `InputParameters` expression, and the `Result` variable. Open the `.py` and confirm the function is defined at **module level** with the exact name/case.
+2. **Confirm it is an invoke fault, not a load fault.** If the job log shows `Error initializing Python engine` / `The specified Python path is not valid` / a `ModuleNotFoundError` from a top-level import / a syntax error, route to [load-script-failures.md](./load-script-failures.md) — `InvokeMethod` never executed.
+3. **Decision tree** (stop at the first match):
+   - `AttributeError` / "has no attribute '<name>'" → **M1**. Diff `Name` against the `def` (exact case); check the function is not nested or `__main__`-guarded.
+   - `TypeError` about argument count / missing argument → **M2** (count/order). A marshalling complaint about a non-primitive argument → **M2** (type).
+   - Designer compile error on `InputParameters` (`BC36754` / `CS1503` / `CS0029`) → **M3**.
+   - `One or more errors occurred` with a Python traceback naming a line inside the function → **M4**. Read the traceback for the Python exception type (`FileNotFoundError`, `KeyError`, lazy-import `ModuleNotFoundError`).
+   - `System.IO.PipeException` / "Pipe is broken" → **M5**. Check the size of the returned object and the `Script Data Size Limit`.
+   - `NullReferenceException` on `Instance` → **M6**. Verify `LoadScript` ran and its `Result` is set.
+4. **Capture the Python-side traceback (decisive for M4).** Enable **Log Python Output to File** on the `Python Scope` to capture the Python `stderr`/traceback, then reproduce — the wrapped `One or more errors occurred` rarely shows the originating Python line on its own.
+5. **Reproduce the call standalone.** With the scope's interpreter, from the scope's `WorkingFolder`: `"<Path>\python.exe" -c "import <module>; print(<module>.<Name>(<args>))"`. If it fails the same way, the fault is the script/arguments (M1/M2/M4), not UiPath wiring.
+
+## Resolution
+
+- **M1 — name does not resolve:** set `Name` to the exact, case-correct module-level function name. Move the target function out of a class / outer function / `if __name__ == "__main__":` block so `LoadScript` binds it at module level.
+- **M2 — argument mismatch:** align `InputParameters` count, order, and types with the function signature. Pass only primitives/strings; for structured input, serialize to JSON or write to a file and pass the path. Give Python defaults for optional parameters rather than relying on UiPath to omit them.
+- **M3 — `InputParameters` not an Object array:** wrap the arguments as an object array — C#: `new object[] { var1, var2 }`; VB: `New Object() { var1, var2 }`. A single argument still needs the array wrapper.
+- **M4 — Python exception in the function:** read the traceback (step 4) and fix the Python cause. For the common relative-path case, use absolute paths in the script **or** pass the path in from UiPath as a parameter (do not rely on `open("data.csv")` resolving against the script folder — it resolves against UiPath's working directory). For a lazy-import `ModuleNotFoundError`, install the module into the interpreter at the scope's `Path` (see [load-script-failures.md](./load-script-failures.md) **L2a**).
+- **M5 — broken pipe / oversized payload:** stop returning large objects (DataFrames, big JSON) across the boundary — write them to a `.csv`/`.xlsx` in the script and return the file path or a boolean; raise **Script Data Size Limit (MB)** only if a moderately larger payload is genuinely needed. If the pipe drops instantly on every call, rule out a bitness mismatch via [load-script-failures.md](./load-script-failures.md) **L1b**.
+- **M6 — null `Instance`:** ensure `Load Python Script` runs successfully before `Invoke Python Method` and that the `Instance` binds that activity's `Result` variable. If `LoadScript` is failing, resolve that first via [load-script-failures.md](./load-script-failures.md).
+
+**Prevention.** Validate the function name (exact case, module-level) and the argument contract before running in UiPath by calling it with the scope's own interpreter from the scope's `WorkingFolder`. Keep the Python↔UiPath boundary to primitives and file paths, and enable **Log Python Output to File** during development so the originating Python traceback is visible rather than the wrapped `One or more errors occurred`.
+
+If `Invoke Python Method` still fails after M1–M6 are ruled out, capture the `.py` file, the resolved activity properties from the `.xaml`, the Python-side traceback (Log Python Output to File), and a `Verbose` robot log, and open a UiPath support case.

package/skills/uipath-troubleshoot/references/activity-packages/python-activities/playbooks/invoke-python-method-pipe-is-broken.md

@@ -0,0 +1,44 @@
+---
+confidence: medium
+---
+
+# Python Scope — Pipe is Broken / Error Invoking Python Method
+
+## Context
+
+What this looks like:
+- `Invoke Python Method` or `Run Python Script` (sometimes `Python Scope` itself) faults with:
+  - `Python Scope: Pipe is broken` / `Invoke Python Method: Pipe is broken`, or
+  - `RemoteException wrapping System.IO.IOException: Pipe is broken`, or
+  - `Error invoking Python method`.
+- The same script "runs fine in my IDE / Jupyter / command prompt."
+- The fault appears at the first activity that actually executes Python code, not at scope open.
+
+What can cause it (the Python-side cause is hidden — UiPath only reports that the host process died):
+- **Missing pip module in the scope's interpreter** — the script `import`s a third-party module (e.g. `pandas`, `numpy`, `requests`) that is installed in the developer's IDE interpreter but **not** in the interpreter the `Python Scope` `Path` resolves to. The `ModuleNotFoundError` kills the Python host before it can return; the pipe breaks. Most common cause.
+- **Unhandled exception in the script** — any uncaught Python exception (bad data, a `KeyError`, a failed file open) crashes the host the same way.
+- **Hard process exit** — the script calls `sys.exit()` / `os._exit()` / `quit()`, or a native extension segfaults, terminating the host.
+- **Flooding stdout** — printing very large volumes to the console can overwhelm the pipe buffer and break communication.
+
+What to look for:
+- The script's `import` lines vs what is installed in the scope's interpreter (`<scope-path>\python.exe -m pip list`).
+- Whether the interpreter the scope points to is the same one the user tested in their IDE.
+- Any top-level `sys.exit` / `os._exit` / `quit`, or large `print` loops, in the script.
+- Whether the script raises on the robot's input data specifically (works on dev data, fails on production data).
+
+## Investigation
+
+1. Read the error from job evidence. Confirm the signature is `Pipe is broken` / `Error invoking Python method` and the faulted activity is `Invoke Python Method` / `Run Python Script` (not an interpreter-resolution fault at `Python Scope` — that is a different playbook).
+2. Read the `.py` file(s) referenced by `Load Python Script` / `Run Python Script` from the project source. List every `import`, especially third-party modules. Note any top-level `sys.exit` / `os._exit` / `quit` and any heavy stdout output.
+3. Capture the `Python Scope` `Path` / `Version` / `Target` from the `.xaml` — this identifies the exact interpreter that runs at robot runtime.
+4. Establish (ask the user if not in logs) whether the third-party modules are installed in **that** interpreter, and whether the IDE where it "runs fine" uses the same interpreter. These usually differ — that gap is the cause.
+5. Have the user reproduce the real Python error out-of-band: run the script directly from the scope's interpreter, `<scope-path>\python.exe <script.py>`. The standalone run prints the true traceback (e.g. `ModuleNotFoundError: No module named 'pandas'`) that UiPath swallowed.
+
+## Resolution
+
+- **If a third-party module is missing from the scope's interpreter:** install it into that exact interpreter — `"<scope-path>\python.exe" -m pip install <module>` — not into the dev's IDE environment. On unattended robots, install under the robot user (or use a virtual environment and point `Path` at it). Re-run; the pipe no longer breaks.
+- **If the script raises an unhandled exception:** wrap the body in `try/except`, log the real error, and re-raise or return a clean result so UiPath surfaces the cause instead of a broken pipe. Fix the underlying exception. Pin down whether it is data-dependent (only the robot's input triggers it).
+- **If the script hard-exits or floods stdout:** remove `sys.exit()` / `os._exit()` / `quit()` from the invoked code path (let functions `return` instead), and stop printing large volumes to the console — write to a file or return the data via the method result.
+- **General prevention:** keep Python logic in functions returning values (no top-level side-effects), standardize the robot interpreter (a checked-in `requirements.txt` installed into the scope's interpreter or venv), and confirm the script runs standalone from the robot interpreter before wiring it into the workflow.
+
+If the failure persists after the imported modules are confirmed installed in the scope's interpreter and the script runs standalone from that interpreter, capture a `Verbose` robot log plus the standalone traceback and open a UiPath support case — residual cases are package/interpreter-version-specific.

package/skills/uipath-troubleshoot/references/activity-packages/python-activities/playbooks/load-script-failures.md

@@ -0,0 +1,62 @@
+---
+confidence: medium
+---
+
+# Load Python Script (LoadScript) Failures
+
+## Context
+
+`UiPath.Python.Activities.LoadScript` ("Load Python Script") runs inside a `Python Scope`, reads a `.py` file (or inline script text), **executes the module body to bind the functions/objects it defines**, and returns a `PythonObject` for downstream `Invoke Python Method`. A `LoadScript` failure means execution never got past load — either the `Python Scope` could not initialize the engine (a scope-layer fault that surfaces when the first child runs) or the script itself failed to load/import. Invocation-time failures (a called function throwing) are out of scope — that is `Invoke Python Method`.
+
+A strong tell: the script runs fine in an IDE (PyCharm / VS Code) but fails under UiPath. The IDE uses its own venv/conda environment; the `Python Scope` only sees the interpreter at its `Path` plus Windows environment variables, and does **not** auto-activate a venv/conda env.
+
+What this looks like:
+- `The specified Python path is not valid` (even when `python.exe` opens manually).
+- `Error initializing Python engine 64 bit` / engine fails to start.
+- `One or more errors occurred` / `Error loading the python script` (generic wrapper around a Python-side syntax error, top-level exception, or failed import).
+- `ModuleNotFoundError: No module named 'xyz'`.
+- The scope hangs indefinitely on load, or fails with a data-size error.
+
+## Causes
+
+Name the confirmed sub-cause exactly. Do NOT assert a cause unless the investigation arrived at it.
+
+- **L1. Engine initialization failure (scope layer).** The `Python Scope` cannot stand up the interpreter, so `LoadScript` (the first child) is where it surfaces. Sub-causes:
+  - **L1a. `Path` wrong.** `Path` must be the **Python installation or virtual-environment folder** (the one whose `python.exe` and `site-packages` you want) — not the path to `python.exe` itself, and not a "libraries" folder. A trailing slash or a path that resolves only on the developer machine produces `The specified Python path is not valid`.
+  - **L1b. Bitness mismatch.** `Target` (`x86`/`x64`) does not match the installed interpreter's bitness. Produces `Error initializing Python engine`. The interpreter bitness — not the OS — is what `Target` must match.
+  - **L1c. `Library path` wrong/missing for Python > 3.9 (Windows).** On Windows with Python **> 3.9**, `Library path` must point at the matching `pythonXX.dll` (e.g. `python311.dll`); leaving it empty fails engine init. On Windows with Python **≤ 3.9** it must be **empty**. On Linux it must point at `libpythonXX.so`.
+  - **L1d. `Version` unsupported by the package.** The pinned `Version` (or an `Auto`-detected interpreter) is newer than the `UiPath.Python.Activities` package supports (3.10→v1.6.0, 3.11→v1.7.1, 3.12→v1.8.1, 3.13→v1.10.0, 3.14→v2.2.1).
+  - **L1e. .NET Desktop Runtime missing.** Windows projects on package **v1.9.0+** require the **.NET Desktop Runtime 6+** (.NET 8 also supported). Without it the engine cannot initialize.
+- **L2. Script load / compile / import error (script layer).** The engine initialized, but executing the module body failed. Surfaces as `One or more errors occurred` / `Error loading the python script`. Sub-causes:
+  - **L2a. `ModuleNotFoundError`.** The interpreter at `Path` lacks the imported package. The IDE had it (different env); the robot's interpreter does not. Most common when `Path` points at a system Python while the dependencies live in a venv/conda env (or vice-versa).
+  - **L2b. Syntax error or top-level exception.** A syntax typo, or loose executable code at module level that raises during load. `LoadScript` runs the module body, so anything outside a `def` executes at load time.
+  - **L2c. Unresolved local import.** The script `import`s a sibling `.py` that is not found because `WorkingFolder` does not point at the script's project root, so the relative import path resolves wrong.
+- **L3. Hang or oversized data.** The script loads but the workflow stalls or errors on volume. Sub-causes: excessive stdout during load freezing the engine pipe; a long-running load exceeding `Timeout`; or a returned object larger than the **Script Data Size Limit** (default 25 MB).
+
+## Investigation
+
+1. **Read the scope + script from the `.xaml`.** Capture `Path`, `Library path`, `Version`, `Target`, `WorkingFolder`, and the `LoadScript` file path / inline text. Note any top-level (non-`def`) code in the script.
+2. **Decision tree** (stop at the first match):
+   - `The specified Python path is not valid` / `Error initializing Python engine` → **L1**. Work the sub-causes in order: confirm `Path` is the install/venv **folder** (L1a); compare interpreter bitness to `Target` (L1b); for Python **> 3.9** on Windows confirm `Library path` points at `pythonXX.dll`, for ≤ 3.9 confirm it is empty (L1c); confirm the Python version is `≤` the package max (L1d); confirm .NET Desktop Runtime 6+ is installed (L1e).
+   - `ModuleNotFoundError: No module named 'xyz'` → **L2a**. Confirm whether `xyz` is installed in the interpreter at `Path` (not the IDE env).
+   - `One or more errors occurred` / `Error loading the python script` with no module error → **L2b/L2c**. Look for top-level code and local imports.
+   - Hang, timeout, or a data-size error → **L3**.
+3. **Run the script standalone with the scope's interpreter** (decisive for L1 vs L2): `cd <WorkingFolder>` then `"<Path>\python.exe" your_script.py`. If it fails here, the fault is the environment/script (L1c/L1d at the interpreter level, or L2) — not UiPath wiring. If it succeeds here but fails in UiPath, the fault is scope configuration (L1a/L1b/L1e) or `WorkingFolder` (L2c).
+4. **For L2a, prove the gap:** `"<Path>\python.exe" -m pip show <module>` against the interpreter at `Path`. Empty output → the module is not in that environment.
+5. **Confirm the interpreter facts:** version (`python --version`) and bitness (`python -c "import struct;print(struct.calcsize('P')*8)"`); and `dotnet --list-runtimes` for `Microsoft.WindowsDesktop.App 6`/`8` (L1e).
+
+## Resolution
+
+- **L1a — wrong `Path`:** set `Path` to the Python install/venv **folder** (the one containing `python.exe` and `site-packages`), e.g. `C:\Users\<USER>\AppData\Local\Programs\Python\Python311` or your venv root. Use the **Installed Python Versions** picker to auto-fill `Path`, `Library path`, and `Target` correctly.
+- **L1b — bitness mismatch:** set `Target` to match the installed interpreter (install a 64-bit Python for `x64`, or set `Target = x86` for a 32-bit interpreter).
+- **L1c — `Library path`:** Python **> 3.9** on Windows → set `Library path` to the matching `pythonXX.dll` (e.g. `<Path>\python311.dll`). Python **≤ 3.9** on Windows → leave it **empty**. Linux → point it at `libpythonXX.so`.
+- **L1d — version unsupported:** upgrade `UiPath.Python.Activities` to a version that supports the Python version (see the package map above), or pin `Version` to a supported interpreter.
+- **L1e — runtime missing:** install the **.NET Desktop Runtime 6+** on the robot host (.NET 8 supported).
+- **L2a — `ModuleNotFoundError`:** point `Path` at the environment whose `site-packages` has the module, **or** install the dependency into the interpreter at `Path` (`"<Path>\python.exe" -m pip install <module>`). Do not rely on the IDE's venv being picked up — it is not.
+- **L2b — syntax / top-level error:** fix the syntax, and move executable logic into functions. Keep the module body to `def`s and imports (optionally guard run-on-load logic with `if __name__ == "__main__":`); `Load Python Script` only needs the functions defined, and invokes them via `Invoke Python Method`.
+- **L2c — local import not found:** set `WorkingFolder` to the script's project root so relative `import`s resolve.
+- **L3 — hang / oversized data:** remove or reduce stdout produced at load (and keep **Log Python Output to File** off in production); raise `Timeout` for a legitimately slow load; for large returns, write the data to a file in the script and pass the file path back instead of the object, or raise **Script Data Size Limit (MB)**.
+
+**Prevention.** Before running in UiPath, run the script with the **same interpreter** the scope points at, from the scope's `WorkingFolder`. Configure the scope via the **Installed Python Versions** picker so `Path`, `Library path`, and `Target` are mutually consistent, and confirm the package version supports the Python version.
+
+If `LoadScript` still fails after L1–L3 are ruled out, capture the `.py` file, the resolved scope properties from the `.xaml`, the interpreter version/bitness, and a `Verbose` robot log (or enable **Log Python Output to File** locally to capture the Python-side traceback), and open a UiPath support case.

package/skills/uipath-troubleshoot/references/activity-packages/python-activities/playbooks/python-path-not-valid.md

@@ -0,0 +1,39 @@
+---
+confidence: high
+---
+
+# Python Scope — The Specified Python Path Is Not Valid
+
+## Context
+
+What this looks like:
+- `Python Scope` faults immediately on open with:
+  - `Python Scope: The specified Python path is not valid: <path>`.
+- The fault is at scope open — no Python code has run yet.
+- The `<path>` in the error is exactly the `Path` property value, and the file/folder it names does exist on disk, so "the path is right, why is it invalid?"
+
+What can cause it:
+- **`Path` points at `python.exe` instead of the install folder** — the most common cause. `Path` must be the **folder** that contains `python.exe` (e.g. `C:\Program Files\Python311`), not the executable itself (`C:\Program Files\Python311\python.exe`). The scope appends the interpreter name internally.
+- **`Path` points at the Microsoft Store alias** — `%LocalAppData%\Microsoft\WindowsApps\python` (or `...\python.exe`) is a 0-byte execution-alias stub installed by the Store "App execution aliases", not a real Python install. The scope cannot resolve a real interpreter from it.
+- **`Path` resolves to an interpreter the robot user can't see** — a per-user install under the developer's profile (`C:\Users\<dev>\AppData\Local\Programs\Python\...`) does not exist for the unattended robot user. From the robot's perspective the path is invalid.
+- **`Library path` / `Version` mismatch** (Python > 3.9 on Windows) — `Path` is correct but `Library path` does not point at the matching `pythonXY.dll`, so the engine can't bind. (If the error is `One or more errors occurred` / `Error initializing the Python engine` rather than "path is not valid", use the architecture/version playbook instead.)
+
+What to look for:
+- The trailing segment of the `Path` value: does it end in `\python.exe`? Is it under `\WindowsApps\`?
+- Whether the path is under a per-user profile (`C:\Users\<name>\...`) that differs between the developer and the robot user.
+
+## Investigation
+
+1. Read the error from job evidence. Confirm it is `The specified Python path is not valid: <path>` at `Python Scope` (not a `Pipe is broken` or engine-init error — different playbooks).
+2. Read the `Python Scope` `Path` property from the `.xaml`. Compare the literal against the two traps: a `\python.exe` suffix, or a `\WindowsApps\python` Store-alias path.
+3. If `Path` is a folder and not a Store alias, check whether it is under a per-user profile (`C:\Users\<dev>\...`) that the unattended robot user would not have.
+4. Confirm the real interpreter location out-of-band: the install **folder** that contains `python.exe` on the robot host (e.g. `where python` / the actual `Programs\Python\PythonXXX` folder).
+
+## Resolution
+
+- **If `Path` ends in `\python.exe`:** remove the executable name — set `Path` to the containing folder only. Example: change `C:\Program Files\Python311\python.exe` → `C:\Program Files\Python311`.
+- **If `Path` is the `WindowsApps\python` Store alias:** install Python from python.org (or use an existing real install) and point `Path` at that install folder. Disable the Store "App execution aliases" for `python` / `python3` (Settings → Apps → Advanced app settings → App execution aliases) so the alias stops shadowing the real interpreter on `PATH`.
+- **If `Path` is a per-user install the robot can't see:** install Python for **all users** (machine-wide, e.g. `C:\Program Files\Python311`) or install it under the robot's own user, then point `Path` at a folder the robot user can read.
+- **After fixing `Path`** (Python > 3.9 on Windows): set `Library path` to the matching `pythonXY.dll` in that folder (e.g. `C:\Program Files\Python311\python311.dll`) and set `Version` to the installed version; leave `Library path` empty for installs ≤ 3.9. Re-run and confirm the scope opens.
+
+This is a high-confidence configuration fix: the error names the exact bad `Path`, and the scope opening successfully after the edit is immediate confirmation.

package/skills/uipath-troubleshoot/references/activity-packages/python-activities/playbooks/python-scope-architecture-version-mismatch.md

@@ -0,0 +1,41 @@
+---
+confidence: medium
+---
+
+# Python Scope — One or More Errors Occurred / Engine Init (Architecture & Version Mismatch)
+
+## Context
+
+What this looks like:
+- `Python Scope` faults on open with a generic aggregate error:
+  - `One or more errors occurred.`, or
+  - `Error initializing the Python engine`, or a `BadImageFormatException` / "is not a valid Win32 application" style inner error.
+- The `Path` is correct (it is not a "path is not valid" error) and the script hasn't run, so there's no Python traceback to read.
+
+What can cause it:
+- **Bitness mismatch (most common)** — the scope's `Target` does not match the interpreter's architecture. `Target = x86` against a 64-bit Python install (or `Target = x64` against a 32-bit install) cannot load the interpreter's native library into the host process. The UiPath robot process bitness and the Python install bitness must agree with `Target`.
+- **`Version` mismatch** — `Version` is pinned to a release that isn't the one installed (e.g. `Python_310` selected, 3.11 installed), or set to a version the installed `UiPath.Python.Activities` pack doesn't support.
+- **`Library path` wrong or missing** (Python > 3.9 on Windows / Linux) — `Library path` doesn't point at the matching `pythonXY.dll` / `libpythonX.Y.so`, so the engine can't bind to the interpreter.
+- **Missing .NET Desktop Runtime** — the Python pack version requires a .NET Desktop Runtime (e.g. 6.0 / 8.0 depending on the Studio/runtime release) that isn't installed on the robot host, so the engine host can't start.
+
+What to look for:
+- The scope's `Target` vs the install's true bitness (32-bit installs live under `C:\Program Files (x86)\`; 64-bit under `C:\Program Files\`, but verify — don't infer from the folder alone).
+- The scope's `Version` vs the installed Python version and the pack's supported-version matrix.
+- Whether `Library path` is set (and correct) for Python > 3.9.
+- The installed .NET Desktop Runtime vs the pack's requirement.
+
+## Investigation
+
+1. Read the error from job evidence. Confirm it is an engine-init / `One or more errors occurred` fault at `Python Scope` (not `The specified Python path is not valid` and not `Pipe is broken` — those are different playbooks).
+2. Read the `Python Scope` `Target`, `Version`, and `Library path` from the `.xaml`.
+3. Establish the interpreter's true architecture and version on the **robot** host out-of-band: run `<scope-path>\python.exe -c "import struct,sys; print(struct.calcsize('P')*8, sys.version)"` — prints `64` or `32` and the version. Compare against `Target` and `Version`.
+4. Read `UiPath.Python.Activities` version from `project.json` and check the installed .NET Desktop Runtime (`dotnet --list-runtimes`) against the pack's required runtime.
+
+## Resolution
+
+- **If `Target` ≠ install bitness:** set `Target` to match the interpreter (`x64` for a 64-bit install, `x86` for a 32-bit install). If a specific bitness is required for a native dependency, install the matching-bitness Python and point `Path` at it.
+- **If `Version` is wrong:** set `Version` to the installed Python version (or `Auto`). If the installed Python is newer than the pack supports, upgrade `UiPath.Python.Activities` to a version whose supported matrix includes that Python — older packs do not support newer Python releases.
+- **If `Library path` is wrong/missing (Python > 3.9):** set it to the matching `pythonXY.dll` in the install folder (e.g. `python311.dll`); leave it empty for installs ≤ 3.9.
+- **If the required .NET Desktop Runtime is missing:** install the .NET Desktop Runtime version the pack requires (per the Studio/runtime release) on the robot host from the Microsoft download portal, then re-run.
+
+After each change, re-open the scope (validate / run) to confirm the engine initializes. If the engine still won't start after `Target`, `Version`, `Library path`, and runtime all match the interpreter, capture a `Verbose` log and open a UiPath support case — residual cases are pack/runtime-version-specific.

package/skills/uipath-troubleshoot/references/activity-packages/python-activities/playbooks/working-folder-relative-path.md

@@ -0,0 +1,34 @@
+---
+confidence: medium
+---
+
+# Python Scope — Script Runs but Reads/Writes the Wrong Files (WorkingFolder / Relative Path)
+
+## Context
+
+What this looks like:
+- The Python activities succeed — no `Pipe is broken`, no scope error — but the automation "doesn't execute properly": the script writes output that never appears where expected, reads a stale/empty file, or a Python-side `FileNotFoundError` references a relative path.
+- Works in Studio / on the developer's machine; misbehaves only on the robot.
+
+What can cause it:
+- **Relative paths resolve against `WorkingFolder`, which defaults to the robot's per-package CWD.** A script that opens `open("data.csv")` or writes `out.json` with a bare/relative name resolves it against the process working directory. `Python Scope` `WorkingFolder` sets that directory; when left blank, the robot's unattended CWD is the per-package folder `%LocalAppData%\UiPath\Packages\<process>\<version>\`, not the project folder. The developer sees it "work" because Studio's CWD is the project folder during debugging.
+- **`WorkingFolder` set to a developer-only path** — an absolute `WorkingFolder` that exists on the dev machine but not on the robot host.
+
+What to look for:
+- Relative file paths inside the `.py` script (`open(...)`, `Path(...)`, `pd.read_csv("...")`, output writes with bare filenames).
+- Whether `Python Scope` `WorkingFolder` is set, and to what.
+- A resolved path in any Python-side error that carries the `%LocalAppData%\UiPath\Packages\...` prefix — the smoking gun for CWD divergence.
+
+## Investigation
+
+1. Confirm the activities did not fault (or faulted only with a Python-side `FileNotFoundError` on a relative path) — distinguishes this from `Pipe is broken` and scope-resolution errors.
+2. Read the `.py` script. List every file path it opens or writes; flag any that is relative (no drive letter, no leading `\`, no UNC).
+3. Read the `Python Scope` `WorkingFolder` from the `.xaml`. Note whether it is blank (defaults to the robot per-package CWD) or an absolute path that may not exist on the robot.
+4. If a Python-side path error is present, check its prefix: a `%LocalAppData%\UiPath\Packages\<process>\<version>\` prefix confirms the relative path resolved against the package CWD.
+
+## Resolution
+
+- **If the script uses relative paths:** make them absolute. Either set `Python Scope` `WorkingFolder` to a stable absolute directory and keep filenames relative to it, or pass absolute paths into the script as method arguments (`Invoke Python Method` `InputParameters`) built in the workflow from an Orchestrator asset / environment variable. Do not rely on the implicit CWD.
+- **If anchoring inside the script:** resolve paths against the script's own location, e.g. `os.path.join(os.path.dirname(os.path.realpath(__file__)), "data.csv")`, so the script is independent of the process CWD.
+- **If `WorkingFolder` is a dev-only absolute path:** point it at a directory that exists on the robot host (or source it from an asset / env var per environment).
+- **Prevention:** ban bare relative paths in scripts invoked from unattended robots; the robot CWD is the per-package sandbox and differs from Studio's project folder.

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

@@ -0,0 +1,9 @@
+# Python Activities Presentation Rules
+
+- **Activities** — use the display name (e.g., "Python Scope", "Invoke Python Method", "Run Python Script", "Load Python Script"), not the fully qualified class name (e.g., `UiPath.Python.Activities.InvokeMethod`)
+- **Scripts** — refer to the Python file by its name (e.g., "script `parse_invoice.py`") or the inline `Code` location; not by the `PythonObject` variable holding the loaded handle
+- **Interpreter** — name the interpreter by its resolved install folder and version (e.g., "the Python 3.11 install at `C:\Program Files\Python311`"), and distinguish it explicitly from the developer's IDE interpreter when the script "runs fine in my IDE"
+- **`Path` property** — when the fix is a folder-vs-file correction, show both the wrong value (`...\Python311\python.exe`) and the corrected value (`...\Python311`) so the user can see the exact edit
+- **Error strings** — quote the exact message (`The specified Python path is not valid: <path>`, `Pipe is broken`, `One or more errors occurred`) and, when present, the wrapping type (`RemoteException wrapping System.IO.IOException`) so the user can correlate it with the Output panel / job log
+- **Bitness** — refer to the interpreter and the scope `Target` as "32-bit (x86)" / "64-bit (x64)", and state which side is which (e.g., "`Target` is x86 but the install is 64-bit")
+- **Run surface** — name the surface in the user's terms (e.g., "Studio Run/Debug (foreground)", "unattended robot (Session 0)"), not internal runtime flags like `isAttended`

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

@@ -0,0 +1,12 @@
+# Python Activities Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Python Activities investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Pipe is broken / Error invoking Python method | Medium | `Invoke Python Method` / `Run Python Script` faults with `Pipe is broken` (often `RemoteException wrapping System.IO.IOException: Pipe is broken`). The out-of-process Python host died and UiPath hides the Python-side cause: a pip module missing from the scope's interpreter, an unhandled exception, a hard `sys.exit`, or flooding stdout. "Runs in my IDE" = different interpreter | [invoke-python-method-pipe-is-broken.md](./playbooks/invoke-python-method-pipe-is-broken.md) |
+| The specified Python path is not valid | High | `Python Scope` fails resolving the interpreter: `The specified Python path is not valid: <path>`. `Path` points at `python.exe` (the file) instead of the install **folder**, or at the `WindowsApps\python` Store alias | [python-path-not-valid.md](./playbooks/python-path-not-valid.md) |
+| One or more errors occurred / Error initializing the Python engine | Medium | `Python Scope` fails to load the interpreter. `Target` bitness (x86/x64) doesn't match the install, `Version`/`Library path` is wrong, or the required .NET Desktop Runtime is missing | [python-scope-architecture-version-mismatch.md](./playbooks/python-scope-architecture-version-mismatch.md) |
+| Script runs but reads/writes the wrong files | Medium | The script completes but relative file paths inside it resolve against `WorkingFolder` — which defaults to the robot's per-package CWD, not the project folder. Same CWD-divergence class as relative workflow paths | [working-folder-relative-path.md](./playbooks/working-folder-relative-path.md) |
+| Load Python Script (LoadScript) Failures | Medium | `UiPath.Python.Activities.LoadScript` fails to load a script. Three families: (L1) **engine initialization** — `The specified Python path is not valid` / `Error initializing Python engine 64 bit` from wrong `Path` (must be the install/venv folder), `Target` bitness mismatch, `Library path` missing for Python > 3.9 on Windows (`pythonXX.dll`), a Python version newer than the package supports, or missing .NET Desktop Runtime 6+ (pkg v1.9.0+); (L2) **script load/import** — `One or more errors occurred` / `Error loading the python script` / `ModuleNotFoundError` from a module missing in the interpreter at `Path` (IDE venv not auto-activated), a top-level syntax error/exception, or an unresolved local import (`WorkingFolder`); (L3) **hang / oversized data** — stdout pipe freeze, `Timeout`, or Script Data Size Limit exceeded | [load-script-failures.md](./playbooks/load-script-failures.md) |
+| Invoke Python Method (InvokeMethod) Failures | Medium | `UiPath.Python.Activities.InvokeMethod` fails after the script loaded. Families: (M1) **name does not resolve** — `AttributeError`/"has no attribute" from a typo, case mismatch (`Name` is case-sensitive), or a function nested in a class / under `if __name__=='__main__'` so `LoadScript` never bound it; (M2) **argument mismatch** — `TypeError` on count/order, or a complex .NET object (`DataTable`) that won't marshal (pass primitives/strings); (M3) **`InputParameters` not an Object array (design-time)** — `BC36754` (VB) / `CS1503`/`CS0029` (C#); wrap as `new object[] {…}`; (M4) **Python exception in the function** — `One or more errors occurred` wrapping a relative-path `FileNotFoundError`, `KeyError`, or lazy-import `ModuleNotFoundError`; (M5) **broken pipe / oversized payload** — `System.IO.PipeException` from too-large a return (write to file, return path) or Script Data Size Limit; (M6) **null `Instance`** — `LoadScript` faulted/skipped. Engine-init / load faults route to load-script-failures | [invoke-method-failures.md](./playbooks/invoke-method-failures.md) |

package/skills/uipath-troubleshoot/references/activity-packages/system-activities/playbooks/get-asset-activity-bug-silent-failure.md

@@ -32,4 +32,4 @@ What to look for:
 ## Resolution
 
 - **If copy-paste issue:** delete the activity and re-drag a fresh one from the Activities panel.
-- **If `Ctrl+K` variable bug (System.Activities 22.10.x):** update the package to ≥22.10.4, or pre-create the variable in the Variables panel before wiring it to the activity.
+- **If `Ctrl+K` variable bug (System.Activities 22.10.x):** update the package to a release after the 22.10.x line (current LTS or newer), or pre-create the variable in the Variables panel before wiring it to the activity. The whole 22.10.x range is affected — do NOT treat a later 22.10.x patch as fixed.

package/skills/uipath-troubleshoot/references/activity-packages/system-activities/playbooks/get-asset-robot-not-authenticated.md

@@ -2,39 +2,46 @@
 confidence: medium
 ---
 
-# Get Asset Failed — Robot Not Authenticated or Unlicensed
+# Get Asset Failed — Robot Not Authenticated
 
 ## Context
 
-A `Get Asset`, `Get Orchestrator Asset`, or `Get Credential` activity failed because the robot is not authenticated or not licensed against Orchestrator.
+A `Get Asset`, `Get Orchestrator Asset`, or `Get Credential` activity
+failed because the robot's Orchestrator API call was rejected as **not
+authenticated** (HTTP 401). This is an identity / API-token failure: the
+robot connected and the job started, but the token the activity uses to
+call the Orchestrator REST API is rejected.
 
 What this looks like:
-- Error message contains `"You are not authenticated! Error code: 0"`
-- Robot shows as `Connected, Unlicensed` in Orchestrator
-- Only Background Process template jobs fail while RE-Framework jobs succeed (package version conflict)
+- Error message contains `"You are not authenticated! Error code: 0"` with HTTP status `401 (Unauthorized)`
+- `UiPath.Core.Activities.OrchestratorCommunicationException` thrown *inside* the running workflow at the asset/credential activity
+- The job has a `StartTime` and ran briefly (often ~1s) before faulting — i.e. it **executed**, then the activity's HTTP call failed
 
-What can cause it:
-- Robot is not licensed in Orchestrator
-- Machine key or client credentials do not match what is configured in Orchestrator
-- `UiPath.System.Activities` package upgrade introduced an authentication regression (versions 20.10.1+ and 2021.10.5)
-- Interactive sign-in not enabled for the tenant
+> **Distinguish from "not authorized" and from "unlicensed":**
+> - "not **authorized**" (HTTP 403) is permission/RBAC — a different playbook (`get-asset-permission-denied.md`), even though it can share `Error code: 0`.
+> - An **unlicensed** robot fails at job *start*: it never acquires a runtime, so the job stays Pending or faults immediately without a `StartTime`/without reaching any activity. A 401 thrown *inside* a running workflow is NOT a licensing symptom. Verify the robot is licensed (`IsLicensed: true`) and that the job actually ran before pursuing this playbook.
+
+What can cause it (in a running job that 401s at the activity):
+- Machine key or client credentials do not match what is configured in Orchestrator (e.g. the machine key was regenerated, or the robot was provisioned against a different machine template). Dispatch can still succeed from a cached session while fresh API-token requests get 401.
+- Robot key authentication is disabled for the tenant ("Allow both user authentication and robot key authentication" is off), so a machine-key-authenticated robot's API token is rejected.
+- A `UiPath.System.Activities` package upgrade introduced an authentication regression (historically reported on 20.10.1+ and 2021.10.5) — suspect this when the failure began right after a package change.
 
 What to look for:
-- Robot connection status in the UiPath Assistant tray icon (Connected + Licensed vs Connected + Unlicensed)
-- `UiPath.System.Activities` package version in the project
-- Whether the issue started after a package upgrade
+- Robot connection + license status in the UiPath Assistant tray icon (must be Connected **and** Licensed) and in `or users list` (`IsLicensed`, `ConnectionState`)
+- Whether the job actually started/ran (a `StartTime` + an in-`Main.xaml` activity fault) vs. never starting (licensing) — see the unlicensed note above
+- `UiPath.System.Activities` package version in the project, and whether the issue started after a package upgrade
 
 ## Investigation
 
-1. Check the UiPath Robot tray icon — verify it shows "Connected, Licensed".
-2. If unlicensed, check the license assignment in Orchestrator > Tenant > Licenses.
-3. Verify the robot's machine key or client credentials match what is configured in Orchestrator.
-4. Check whether the issue started after a `UiPath.System.Activities` package upgrade — versions 20.10.1+ and 2021.10.5 introduced authentication regressions.
-5. If only Background Process template jobs fail (not RE-Framework), the cause is likely a package version conflict.
+1. Confirm the job **ran** — check for a `StartTime` and that the fault is inside `Main.xaml` at the asset activity. If the job never started (no `StartTime`, stuck Pending, instant fault with a licensing/no-slot message), this is a licensing/runtime-availability issue, not this playbook.
+2. Verify the robot is **licensed and connected** in `or users list` (`IsLicensed: true`, a non-null `LicenseType`, `ConnectionState: Connected`). If unlicensed, assign a Runtime license (Orchestrator > Tenant > Licenses) — that is a separate, start-time failure mode.
+3. Verify the robot's machine key or client credentials match what is configured in Orchestrator > Tenant > Machines. A regenerated/rotated key the robot still holds is the most common cause of a running-job 401.
+4. Check tenant security: confirm "Allow both user authentication and robot key authentication" is enabled (Orchestrator > Tenant > Settings > Security).
+5. Check whether the issue started after a `UiPath.System.Activities` package upgrade — a known auth regression can produce this 401.
 
 ## Resolution
 
-- **If unlicensed:** assign a Runtime license to the robot in Orchestrator.
-- **If machine key mismatch:** reconnect the robot using the correct key from Orchestrator > Machines.
-- **If package regression:** downgrade `UiPath.System.Activities` to v20.4.x as a workaround, or update to the latest stable version.
-- **If interactive sign-in not enabled:** enable "Allow both user authentication and robot key authentication" in Tenant Settings > Security.
+- **If machine key mismatch:** reconnect the robot using the correct key from Orchestrator > Tenant > Machines, then confirm it returns to `Connected, Licensed`.
+- **If robot key authentication disabled:** enable "Allow both user authentication and robot key authentication" in Tenant > Settings > Security.
+- **If package regression:** roll back `UiPath.System.Activities` to the last known-good version, or update to the latest stable, then republish.
+- **If the robot is actually unlicensed (job never started):** assign a Runtime license to the robot in Orchestrator > Tenant > Licenses. Note this presents as a job-start failure, not an in-activity 401.

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

@@ -9,7 +9,7 @@
 | Get Asset — Permission Denied | High | Robot account lacks View permission on Assets (HTTP 403, error code 0) | [get-asset-permission-denied.md](./playbooks/get-asset-permission-denied.md) |
 | Get Asset — Folder Scope Mismatch | High | Wrong `OrchestratorFolderPath` or classic/modern folder incompatibility (error codes 1100, 1101) | [get-asset-folder-scope-mismatch.md](./playbooks/get-asset-folder-scope-mismatch.md) |
 | Get Asset — Per-Robot Asset Has No Value | High | Per-robot asset has no value entry for the executing robot | [get-asset-per-robot-no-value.md](./playbooks/get-asset-per-robot-no-value.md) |
-| Get Asset — Robot Not Authenticated or Unlicensed | Medium | Robot not authenticated or not licensed against Orchestrator (error code 0, package regressions) | [get-asset-robot-not-authenticated.md](./playbooks/get-asset-robot-not-authenticated.md) |
+| Get Asset — Robot Not Authenticated | Medium | Running job's Orchestrator API call rejected as not authenticated (HTTP 401, error code 0): machine-key mismatch, robot-key auth disabled, or System.Activities auth regression. Distinct from an unlicensed robot, which fails at job start | [get-asset-robot-not-authenticated.md](./playbooks/get-asset-robot-not-authenticated.md) |
 | Get Asset — External Credential Store Failure | Medium | External vault (CyberArk, Azure Key Vault, Thycotic) unreachable or misconfigured (error codes 2303, 2304) | [get-asset-external-vault-failure.md](./playbooks/get-asset-external-vault-failure.md) |
 | Get Asset — Activity Bug / Silent Failure | Medium | Activity completes without exception but output is null/zero/empty (copy-paste or package 22.10.x bug) | [get-asset-activity-bug-silent-failure.md](./playbooks/get-asset-activity-bug-silent-failure.md) |
 | Get Asset — Network or Connectivity Issue | Low | Network, TLS, proxy, or session expiry between robot and Orchestrator | [get-asset-network-connectivity.md](./playbooks/get-asset-network-connectivity.md) |