@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/create-folder-invalid-path.md

@@ -0,0 +1,36 @@
+---
+confidence: high
+---
+
+# O365 Files — Create Folder invalid name or path
+
+## Context
+
+What this looks like — **Create Folder** (`CreateFolderConnections`) faults on its own input validation before or while walking the target path. All surface as `Office365Exception`:
+
+- `Value cannot be null. (Parameter 'Folder name')` — `FolderCreationMode = FolderName` but the name argument is empty/null.
+- `Value cannot be null. (Parameter 'Folder path')` — `FolderCreationMode = FolderPath` but the path argument is empty/null.
+- `Value cannot be null. (Parameter 'Parent folder')` — parent selection mode is "use existing" but the bound parent item is null or not a resolvable folder reference.
+- `Folder path must contain at least one segment.` — the path is non-empty but reduces to zero segments after splitting (e.g., only separators). May carry a `(Parameter 'FolderPath')` suffix.
+- `Folder path segment '<segment>' cannot have leading or trailing whitespace.` — a path segment has surrounding spaces. May carry a `(Parameter 'FolderPath')` suffix.
+- `Cannot create folder path: '<segment>' is a file, not a folder.` — an intermediate segment of the path already exists as a **file**, so the folder chain cannot be created through it.
+
+The failure is deterministic — same configuration, same fault, no dependency on Graph-side state except the segment-is-a-file case.
+
+What can cause it:
+- **Empty/null name or path argument** — the bound variable is empty at runtime (unassigned, or an expression that evaluates to empty for some inputs).
+- **Null parent item** — the parent folder variable comes from an upstream lookup that matched nothing.
+- **Path built with stray separators or padded segments** — string composition producing `folder1/ folder2` or `//folder`.
+- **A file already occupying a path segment name** — the path expects `Reports/2024` to be folders but `Reports` (or `2024`) exists as a file.
+
+> **Different cause, do not apply this playbook:**
+> - `The specified item name already exists.` — the final folder already exists with `ConflictResolution = Fail`; use [item-name-already-exists.md](./item-name-already-exists.md).
+> - `The resource could not be found.` / `Cannot find item configured with connection ...` — the configured **parent** folder doesn't resolve; use [drive-item-not-found.md](./drive-item-not-found.md).
+
+## Resolution
+
+The message names the defective input; no further investigation is needed. Fix the configuration:
+
+1. **For `Value cannot be null. (Parameter '<name>')`:** read the named property on the activity in the workflow source. If bound to a variable, trace why it's empty at runtime (unassigned, conditional, empty upstream output) and fix the assignment; for `Parent folder`, also confirm the upstream lookup actually returned a folder.
+2. **For segment errors (`at least one segment` / `leading or trailing whitespace`):** inspect the composed path value — trim each segment and remove duplicate/trailing separators where the path is built from variables.
+3. **For `'<segment>' is a file, not a folder.`:** check OneDrive/SharePoint at the parent location — rename/move the conflicting file, or change the folder path to avoid the name.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/download-file-conversion-or-destination.md

@@ -0,0 +1,40 @@
+---
+confidence: high
+---
+
+# O365 Files — Download conversion or destination error
+
+## Context
+
+What this looks like — a download/export operation faults on the item type, the PDF conversion, or the local destination (not on resolving the remote item). All are package-fixed messages thrown as `Office365Exception` from the shared download/export service, so the exception type is `Office365Exception` on **both** the Connections and legacy activities:
+
+- `Folders cannot be downloaded with this activity. Please input a different DriveItem.` — the configured item is a folder.
+- `Cannot convert the item into PDF format. The supported source extensions are: csv, doc, docx, odp, ods, odt, pot, potm, potx, pps, ppsx, ppsxm, ppt, pptm, pptx, rtf, xls, xlsx.` — PDF conversion requested for an unsupported source type.
+- `Local File Path should point to a folder or directly to a .pdf file.` — PDF export destination has a non-`.pdf` file extension.
+- `File should have a name: '<name>'.` — the destination filename reduces to empty; can also surface wrapped as `Value cannot be null. (Parameter 'File should have a name: ...')`.
+- `Cannot locate file. Please ensure that you have proper permissions to access it.` — the parent drive of a **shared** item could not be resolved with the current permissions (shared-with-me items whose parent isn't accessible).
+
+What activities can produce this error:
+- **Download File** (`DownloadFileConnections`) — including its convert-to-PDF option.
+- Legacy **Download File** (`DownloadFile`) and **Export As PDF** (`ExportAsPdf`).
+- Copy/Download paths operating on shared items (the `Cannot locate file ...` form).
+
+What can cause it:
+- **Folder bound where a file is required** — upstream search returned a folder, or a browse selection points at a folder.
+- **Unsupported conversion source** — e.g., `.txt`, `.png`, `.msg` with PDF conversion enabled; only the listed Office/text formats convert.
+- **Destination misconfiguration** — local path ends in a non-`.pdf` filename for PDF export, or composes to an empty filename.
+- **Shared-item permission gap** — the item was shared item-only; the connection cannot resolve its parent drive.
+
+> **Different cause, do not apply this playbook:**
+> - `The resource could not be found.` / `A file with the specified ID does not exist.` — the remote item doesn't resolve; use [drive-item-not-found.md](./drive-item-not-found.md).
+> - `Multiple items with the name <name> found ...` — local destination name conflict; use [download-multiple-items-name-conflict.md](./download-multiple-items-name-conflict.md).
+
+## Resolution
+
+The message identifies the misconfiguration; no further investigation is needed. Fix per message:
+
+1. **Folder input:** point the activity at a file — to download a folder's contents, iterate with **For Each File/Folder** (`ForEachFileFolderConnections`) and download per file.
+2. **Unsupported PDF source:** only the listed extensions convert. Disable conversion for other types or convert upstream (e.g., download raw, convert locally).
+3. **Non-`.pdf` destination:** set the local path to a folder or a filename ending in `.pdf`.
+4. **Empty filename:** inspect the expression composing the destination name — ensure it yields a non-empty name for every input.
+5. **Shared-item permission gap (`Cannot locate file ...`):** have the owner share the containing folder (not just the file) or grant the connection's account access to the parent; then re-run.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/drive-item-not-found.md

@@ -29,7 +29,7 @@ What activities can produce this error:
 - **Check In/Out File** (`CheckinCheckoutFileConnections`) — when the target `File` doesn't resolve.
 - **Assign Sensitivity Label** (`AssignSensitivityLabelConnections`), **Get Sensitivity Labels** (`GetSensitivityLabelsConnections`) — when the target `Item` doesn't resolve.
 - **Wait For File Created** / **Wait For File Updated** (persistence triggers) — when the watched parent `Folder` doesn't resolve.
-- Legacy activities: `DownloadFile`, `ExportAsPdf`, and other files activities that take a `DriveItem` argument.
+- Legacy activities: `DownloadFile`, `ExportAsPdf`, `FindFilesAndFolders`, `ForEachFileFolder`, `CopyItem`, `UploadFile`, `GetItem`, `MoveItem`, `DeleteItem`, `ShareItem`, `CreateFolder`, and other files activities that take a `DriveItem` argument. Legacy activities surface this as a **raw `Microsoft.Graph.ServiceException`** whose message embeds `Code: itemNotFound` plus the same sentence — match the sentence; the raw exception type itself confirms a legacy activity.
 
 What can cause it:
 - **Item no longer exists.** The configured ID, URL, path, or browse selection points to a OneDrive/SharePoint item that has been deleted, moved to the recycle bin, or permanently removed. Graph authoritatively returns 404.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/email-trigger-connection-event-failure.md

@@ -0,0 +1,45 @@
+---
+confidence: medium
+---
+
+# O365 — Email trigger fails to retrieve connection event data
+
+## Context
+
+What this looks like — a Mail trigger (`NewEmailReceived`, `EmailSent`) or its debug/sample run faults while talking to the Integration Service connection layer, **before or instead of** a Microsoft Graph call:
+
+- A raw `UiPath.ConnectionClient.Contracts.ConnectionHttpException` — thrown by the connection client during the trigger's sample/debug event lookup or the connection token fetch. The message embeds the Integration Service HTTP status / error detail.
+- An `Office365Exception` carrying the **identical** message — the activity wrapper preserves the `ConnectionHttpException` text verbatim, so the same failure surfaces under either exception type depending on where it escaped.
+
+What this is NOT: a Graph-side error about the mailbox content. The failure originates at the Integration Service connection (event delivery, sample lookup, or token exchange), so the mailbox, folder, and filter configuration are usually not the cause.
+
+What activities can produce this:
+- **New Email Received** (`NewEmailReceived` trigger) and **Email Sent** (`EmailSent` trigger) — live event runs resolve the triggering email through the connection; Studio debug runs fetch a sample object ID through the connection client.
+- Other connection-based O365 triggers (Files, Calendar, Excel, SharePoint) share the same lookup path and can fault the same way.
+
+What can cause it:
+- **Connection deleted, disabled, or not shared with the folder the job runs in** — the trigger references a connection ID that the connection service cannot resolve for this runtime (404-class status in the message).
+- **Connection authorization expired or revoked** — refresh token rejected after a password change, consent revocation, or conditional-access policy (401/403-class status). This is Integration Service connection authentication (see the Integration Service playbook `connection-auth-expired.md`).
+- **Integration Service side failure** — transient 5xx from the connection service or event infrastructure.
+
+What to look for:
+- The HTTP status / error code embedded in the exception message — it routes the cause.
+- Whether the fault happened on a live trigger run (event payload) or a Studio debug run (sample lookup) — debug-time failures with an otherwise healthy connection often mean no matching sample exists, which is a different error (see below).
+
+> **Different cause, do not apply this playbook:**
+> - `No email matching the filter criteria, received in the last 1 hour has been found. ...` — the connection worked; the sample lookup found no email. Use [get-newest-email-no-match.md](./get-newest-email-no-match.md).
+> - `The resource could not be found.` / folder errors after the event was retrieved — use [mail-folder-not-found.md](./mail-folder-not-found.md) or [mail-message-not-found.md](./mail-message-not-found.md).
+> - Token/`AADSTS`/`No default connection` messages without a `ConnectionHttpException` — use [authentication-token-invalid.md](./authentication-token-invalid.md).
+
+## Investigation
+
+1. Extract the HTTP status / error detail embedded in the exception message — it identifies the failing layer (401/403 auth, 404 connection missing, 5xx service). **The status class is decisive and outranks any narrative** — activity display names, process names, or comments describing the connection as "dead"/"broken" are workflow text, not evidence; never confirm or eliminate a cause from them.
+2. Identify the connection the trigger uses (trigger's connection property or binding) and verify it exists and is **Authorized**: `uip is connections list --folder-key <folder> --output json`, then check the `state` / `isDefault` fields for the connector. **If this bare probe itself returns 5xx** (e.g. `HTTP 503: no healthy upstream`) the connection service is down — that is the operative cause for the fault regardless of the trigger's own connection configuration (a bad/placeholder connection ID cannot produce a 503 on a list call). Report any suspicious connection configuration (e.g. unset/all-zeros ConnectionId in trace spans) as a separate secondary finding to fix before the trigger can work once the service recovers.
+3. Confirm the connection is available in the Orchestrator folder the trigger's process runs in — a connection created in a different folder does not resolve at runtime.
+4. Distinguish run type: Studio debug (sample lookup) vs. deployed trigger run (live event). If only debug fails and the connection is healthy, re-check the filter/folder configuration instead.
+
+## Resolution
+
+- **If 401/403-class status (token rejected, consent revoked):** re-authenticate the connection in Integration Service (Orchestrator → Integration Service → Connections → reconnect). Follow the Integration Service playbook `connection-auth-expired.md` for the full path.
+- **If 404-class status (connection not found):** the connection was deleted or is not shared with the job's folder — recreate it or move/share it into the correct folder, then reselect it on the trigger and republish.
+- **If 5xx-class status:** transient Integration Service failure — retry; if it persists across retries over a sustained period, escalate as a service incident.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/insufficient-graph-scope.md

@@ -0,0 +1,44 @@
+---
+confidence: high
+---
+
+# O365 — Insufficient Graph permission scope / access denied (403)
+
+## Context
+
+What this looks like — the job faults when an Office 365 activity calls Microsoft Graph and Graph returns HTTP 403. The caller is authenticated, but is not permitted to perform the operation. The message is one of:
+
+- `The caller doesn't have permission to perform the action.` — the canonical 403.
+- `Access restricted to the item's owner.`
+- `The action is not allowed by the system.`
+- A raw Microsoft Graph 403 message surfaced verbatim, e.g. `Insufficient privileges to complete the operation.`, `You do not have permissions to open this file in the browser.`, or `Group Shard is used in non-Groups URI.` — these arrive with a Graph error code the package doesn't recognize, so the original Graph text is shown as-is. (The common `accessDenied` code is *not* one of these — it maps to the fixed `The caller doesn't have permission to perform the action.` above.)
+
+What activities can produce this:
+- **Any** Mail, Files/OneDrive, or Excel Online activity. The required permission depends on the operation — common offenders are write/share operations that need broad scopes:
+  - **Send Mail** (`SendMailConnections`) → `Mail.Send`
+  - **Share Item** (`ShareItemConnections`), **Move/Copy/Delete/Upload** (`MoveItemConnections`, `CopyItemConnections`, `DeleteItemConnections`, `UploadFilesConnections`) → `Files.ReadWrite.All` / `Sites.ReadWrite.All`
+  - **Read Range / Write Range** on SharePoint-hosted workbooks (`ReadRangeConnections`, `WriteRangeConnections`) → `Sites.Read.All` / `Sites.ReadWrite.All`
+  - Read operations → the matching `*.Read` scope (`Mail.Read`, `Files.Read.All`, `Sites.Read.All`).
+
+What can cause it:
+- **Missing Graph permission scope.** The connected app registration (application permissions) or the signed-in user (delegated permissions) was never granted / admin-consented the permission the operation requires. With application (app-only) auth the scope set is fixed to the admin-consented permissions on the app — if the needed one isn't there, every call 403s.
+- **App-only impersonation not authorized.** App-only auth is targeting a mailbox/user the app isn't allowed to act for, or that an application-access policy excludes.
+- **Item-owner / sharing restriction.** The caller has the scope but is denied access to the specific resource (a SharePoint/OneDrive item restricted to its owner, or a file blocked from browser open).
+
+> **Different cause, do not apply this playbook:**
+> - `The resource could not be found.` / `Folder named '<name>' could not be found ...` — a missing or mistyped resource. Microsoft Graph sometimes returns **404 instead of 403** for cross-mailbox or shared-resource access the caller isn't entitled to (it hides existence from unauthorized callers). Those cases are covered by **mail-folder-not-found** and **drive-item-not-found**. Practical rule: wrong/mistyped path, name, or id → the not-found playbooks; the target is correct but the caller lacks the Graph permission or is denied access to it → this playbook.
+> - `The caller is not authenticated.` / token-expiry messages — identity couldn't be established. Use **authentication-token-invalid**.
+> - `The sharing link no longer exists, or you do not have permission to access it.` (Graph `accessDenied` / 403, often with an `@onedrive.linkFeatures` annotation, raised while resolving a OneDrive/SharePoint **sharing link**) — this is a **per-resource** failure on one specific shared item (the link was revoked, its sharing scope changed, or the item moved/was deleted), **not** a connection-wide missing scope. A genuine missing scope denies *every* call with the generic `The caller doesn't have permission to perform the action.` / raw `Insufficient privileges to complete the operation.`; this message names the link specifically. Treat it as **drive-item-not-found** (shared-link-no-longer-valid cause) — fix the sharing link, and do **not** keep "missing scope" as a live cause once you see this signature.
+
+## Investigation
+
+1. Confirm the message is a 403 permission pattern above and not a 404 not-found (which has a different message and a different fix).
+2. Identify the failing operation and the Microsoft Graph permission it requires (read vs send vs write/share; OneDrive vs SharePoint Sites). The required scope follows from the operation, not the resource name.
+
+## Resolution
+
+- **If a permission scope is missing:** grant the required delegated or application permission on the app registration and have an administrator consent it — e.g. `Mail.Send` for sending mail, `Files.ReadWrite.All` / `Sites.ReadWrite.All` for sharing or writing files/SharePoint, the matching `*.Read` scope for read operations. Re-run after consent propagates.
+- **If app-only impersonation is denied:** ensure the app is authorized for the target mailbox/site (e.g. the mailbox application-access policy includes the app) and that the impersonated user is correct.
+- **If an item-owner / sharing restriction:** the resource owner must grant the caller access — the caller cannot self-authorize. Confirm the item isn't owner-locked or blocked from the operation.
+
+If the connection already has the required scope consented and the target is correct yet the 403 persists, the cause is outside the activity — escalate (tenant conditional-access policy, sensitivity-label/DLP block, or a SharePoint site permission).

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/legacy-mail-null-reference.md

@@ -0,0 +1,43 @@
+---
+confidence: medium
+---
+
+# O365 Mail — NullReferenceException from legacy Mail activity
+
+## Context
+
+What this looks like — a legacy (non-Connections) Mail activity faults with a raw:
+
+- `System.NullReferenceException: Object reference not set to an instance of an object.`
+
+Routing rule: the **raw exception type itself is the signal**. Connections activities remap an internal NullReferenceException to the friendly text `The object used in the activity does not exist.` — so a raw `NullReferenceException` from this package always means a legacy activity (`UiPath.MicrosoftOffice365.Activities.Mail.SendMail`, `ForwardMail`, `ReplyToMail`, ...) dereferenced a null input before/while building the Graph request.
+
+What activities can produce this error:
+- Legacy **Send Mail** (`SendMail`) — a `null` element inside the `To` / `Cc` / `Bcc` string arrays (e.g., an array built with an unassigned variable), or a null required input dereferenced during message construction.
+- Legacy **Forward Mail** (`ForwardMail`) / **Reply To Mail** (`ReplyToMail`) — the `Message` input is `null`; the activity dereferences it to read the original message ID.
+
+What can cause it:
+- **`Message` not set / upstream returned nothing** — Forward/Reply bound to the output of a Get Mail-style activity that matched no message, so the variable is null.
+- **Null element in a recipient array** — `{var1, var2}` where one variable was never assigned; the array itself is non-null so validation passes, but the null element is dereferenced later.
+- **Any other null required input** consumed during request construction — body/subject composition from null variables.
+
+What to look for:
+- The stack trace — confirms the frames are in `UiPath.MicrosoftOffice365.Activities.Mail.*` (legacy namespace).
+- The faulted activity's input bindings in the workflow source, and where each bound variable is assigned.
+
+> **Different cause, do not apply this playbook:**
+> - `The object used in the activity does not exist.` — same root condition but on the Connections path; investigate that activity's inputs the same way, but the activity is not legacy.
+> - A `NullReferenceException` whose stack trace is in the **user's workflow code** (Assign, Invoke Code), not the package — that is a workflow-logic null; use the general runtime-exception playbook (`references/runtime-exceptions/playbooks/null-reference-exception.md`).
+
+## Investigation
+
+1. Get the stack trace and confirm the top frames are in the legacy Mail activity namespace, not user code.
+2. Identify the faulted activity by `DisplayName` in the workflow source and list its input bindings (`Message`, `To`, `Cc`, `Bcc`, body/subject expressions).
+3. For Forward/Reply: trace the `Message` variable to its producer and check whether the producer can return null/empty (no match, conditional branch).
+4. For Send: inspect array literals for elements that can be null at runtime; check each element variable's assignment.
+
+## Resolution
+
+- **If `Message` is null:** ensure the producing activity actually found a message before forwarding/replying — add an If/null-check (or fix the producer's filter) and handle the no-message case explicitly.
+- **If a recipient array element is null:** assign the variable before the send, or build the array dynamically excluding null/empty entries.
+- **General:** the root cause is WHY the input was null — fix the upstream assignment, then optionally migrate to the Connections equivalent, which validates inputs and reports actionable messages instead of raw NREs.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/mail-folder-not-found.md

@@ -22,6 +22,7 @@ What activities can produce this error:
 - **For Each Email** (`ForEachEmailConnections`) — `MailFolder` argument when the source folder doesn't exist.
 - **Wait For Email Received** (`WaitForEmailReceived`) — `MailFolder` argument when the source folder doesn't exist.
 - **New Email Received trigger** (`NewEmailReceived`) — `MailFolder` argument on the trigger or its debug/healing sample lookup.
+- Legacy **Get Mail** (`GetMail`) — `MailFolder` property when the source folder doesn't resolve.
 - Any other Mail activity that reads a folder.
 
 What can cause it:
@@ -29,10 +30,10 @@ What can cause it:
 - **Wrong mailbox in scope.** The folder exists, but in a different mailbox than the one the activity resolves to (`Account` / `Shared Mailbox`). Common when the connection was re-authenticated against a different account, or when a shared mailbox was passed but the folder lives only in the user's own mailbox (or vice versa).
 - **Stale folder ID.** A folder ID captured from a previous run no longer resolves. Outlook folder IDs are mailbox-scoped — moving the folder between mailboxes invalidates the ID.
 - **Path-segment mismatch.** Folder paths split on `/` and `\`. A folder name that itself contains one of those characters can fail to match. Leading/trailing whitespace or invisible characters in the configured name will also miss the case-insensitive comparison.
-- **Insufficient scope to enumerate.** The connection lacks `Mail.Read` / `Mail.ReadWrite` / `Mail.ReadWrite.Shared` for the target mailbox, so the folder-list enumeration is empty or filtered. Graph may return 404 instead of 403 for cross-mailbox shared/delegated access.
+- **Insufficient scope to enumerate.** The connection lacks `Mail.Read` / `Mail.ReadWrite` / `Mail.ReadWrite.Shared` for the target mailbox, so the folder-list enumeration is empty or filtered. Graph may return 404 instead of 403 for cross-mailbox shared/delegated access. **Ruled out when the trace span exposes `Public.AuthScopesInvalid = False`** — that flag confirms the connection's scopes were valid for this run; do not pursue or recommend scope changes.
 
 > **Different cause, do not apply this playbook:**
-> - `MarkAsReadUnreadConnections`, `DeleteEmailConnections`, `ArchiveEmailConnections`, `DownloadEmailConnections`, and similar message-by-ID activities surface `The resource could not be found.` for a missing **message** (not folder). The fix path is different — verify the message ID and mailbox, not the folder configuration.
+> - `MarkAsReadUnreadConnections`, `DeleteEmailConnections`, `ArchiveEmailConnections`, `DownloadEmailConnections`, and similar message-by-ID activities surface `The resource could not be found.` for a missing **message** (not folder) — use [mail-message-not-found.md](./mail-message-not-found.md).
 
 ## Resolution
 
@@ -42,6 +43,6 @@ The error is unambiguous; no further investigation is needed. Stop the investiga
 2. **Confirm the configured `MailFolder` argument matches** what's in the mailbox. For path-based input, paths split on `/` and `\`, so the activity expects e.g. `Inbox/Subfolder`, not the literal folder name when the folder is nested. For ID-based input, the ID must come from the same mailbox the activity is now running against.
 3. **Confirm the resolved mailbox** (`Account` / shared-mailbox argument) is the one that owns the folder. If the connection has been re-authenticated against a different user, or if the activity is targeting a shared mailbox the connection cannot enumerate, the folder will not appear in the lookup.
 4. **For `MoveEmailConnections`**, ask the user whether the folder is expected to exist beforehand. If the folder should be created on the fly, set `CreateFolderIfMissing = true` to create any missing path segments instead of throwing.
-5. **Confirm the connection's scopes.** The connection must have `Mail.Read` (or `Mail.ReadWrite` for write operations), and `Mail.ReadWrite.Shared` for delegated/shared mailbox access. Missing scopes can surface as a 404 on enumeration even though the folder physically exists.
+5. **Confirm the connection's scopes — only if not already ruled out.** Skip this step entirely when the trace span exposes `Public.AuthScopesInvalid = False`: scopes were valid for this run, so recommending a scope change is a fabricated fix. Otherwise, the connection must have `Mail.Read` (or `Mail.ReadWrite` for write operations), and `Mail.ReadWrite.Shared` for delegated/shared mailbox access. Missing scopes can surface as a 404 on enumeration even though the folder physically exists.
 
 If the user confirms the folder exists with the exact configured name in the resolved mailbox, the connection has the required scopes, and the identifier is correct, the cause is outside the activity — escalate (mailbox-level permissions, retention policy that hid the folder, or a Graph-side delay after a recent rename) rather than continue under this playbook.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/mail-invalid-odata-query.md

@@ -0,0 +1,43 @@
+---
+confidence: high
+---
+
+# O365 Mail — Invalid OData filter query
+
+## Context
+
+What this looks like — a Mail read activity faults while applying its filter/query:
+
+- `Invalid Query. Please use OData format for filter queries. Press F1 for examples.` — the package's fixed message, raised as `Office365Exception` when Microsoft Graph rejects the request with a `RequestBroker--ParseUri` error code (malformed `$filter`). Thrown from the shared Mail proxy, so it surfaces with this exact text from **both** legacy and Connections activities.
+- A raw Graph invalid-filter message surfaced verbatim — other malformed-query Graph codes that don't hit the fixed mapping; on legacy activities inside a raw `Microsoft.Graph.ServiceException` with `Code: BadRequest`, e.g. `Invalid filter clause: ')' or operator expected at position <n> in '<composed filter>'.` (the message echoes the full composed `$filter`, including the date-range clause the activity prepends).
+
+The failure is deterministic: the same query fails every run, independent of mailbox content.
+
+What activities can produce this error:
+- **Get Mail** (legacy `GetMail`) — `Query` property (OData `$filter` string).
+- **Get Newest Email** (`GetNewestEmail`) — `QueryFilter` advanced filter.
+- **Get Email List** (`GetEmailListConnections`), **For Each Email** (`ForEachEmailConnections`) — advanced/raw filter expressions.
+- Mail triggers with filter expressions (`NewEmailReceived`, `WaitForEmailReceived`) on their filter path.
+
+What can cause it:
+- **Malformed OData syntax** — unbalanced quotes/parentheses, missing operators (`eq`, `ge`, `and`), or natural-language text where OData is expected.
+- **Wrong property names** — properties not on the Graph `message` entity (e.g., `sender` vs `from/emailAddress/address`), or wrong casing of a property path.
+- **Unsupported operations** — `$filter` on properties Graph doesn't index for filtering, combining `$search`-only constructs into `$filter`, or unsupported functions.
+- **Bad literal formats** — datetimes not in ISO 8601 (`2024-01-01T00:00:00Z`), unquoted strings, or quoted numerics.
+
+What to look for:
+- The exact filter/query string from the activity's properties in the workflow source.
+- Whether the query ever worked — a previously-working query that now fails usually means the string is built dynamically and an input made it malformed.
+
+> **Different cause, do not apply this playbook:**
+> - `There was an error on the email server. Please try modifying your Query or Top values to continue.` — a Graph `UnknownError` (server-side), not a deterministic parse failure. Use [transient-service-error.md](./transient-service-error.md).
+> - Zero results with no error — the query is valid but matches nothing. Use [get-newest-email-no-match.md](./get-newest-email-no-match.md) for the trigger/no-match case.
+
+## Resolution
+
+The error is unambiguous; the configured query string is rejected by Microsoft Graph. Fix the query:
+
+1. **Read the exact query string** from the failing activity (`Query` / `QueryFilter` / filter expression) in the workflow source. If it's built from variables, log/inspect the final composed value — the defect is often in an interpolated input.
+2. **Validate the syntax against OData for Graph messages:** property paths like `subject`, `from/emailAddress/address`, `receivedDateTime`; operators `eq/ne/gt/ge/lt/le`, `and/or/not`, `startswith()`, `contains()`; ISO 8601 datetimes; single-quoted string literals.
+3. **Test the corrected filter** in Graph Explorer against `/me/messages?$filter=...` until it returns 200, then copy it back into the activity.
+4. **If the query is dynamic:** guard the inputs (escape single quotes, format dates as ISO 8601) before composing the filter.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/mail-message-not-found.md

@@ -0,0 +1,45 @@
+---
+confidence: high
+---
+
+# O365 Mail — Message not found
+
+## Context
+
+What this looks like — a message-by-ID Mail operation cannot resolve the email it was given:
+
+- `The resource could not be found.` — the friendly mapping for Graph `ItemNotFound` (HTTP 404), raised by a **Mail** activity that addresses a specific message ID.
+- `The specified object was not found in the store.` — raw Graph `ErrorItemNotFound` wording; on legacy (non-Connections) activities it surfaces inside a raw `Microsoft.Graph.ServiceException` with `Code: ErrorItemNotFound`.
+- `Item ... doesn't belong to the targeted mailbox ...` — Graph `ErrorInvalidMailboxItemId`: the ID is valid but belongs to a different mailbox than the one the activity resolved.
+- `Id is malformed.` — Graph `ErrorInvalidIdMalformed`: the persisted ID was corrupted or truncated rather than pointing to a removed message. Outlook REST IDs are integrity-checked, so any altered/garbled stored ID surfaces as malformed, not as not-found. Same causes and fixes as a stale ID.
+
+The job faults the moment the activity dereferences the message ID.
+
+What activities can produce this error:
+- Modern: **Get Email By Id** (`GetEmailByIdConnections`), **Forward Email** (`ForwardEmailConnections`), **Reply To Email** (`ReplyToEmailConnections`), **Mark As Read/Unread** (`MarkAsReadUnreadConnections`), **Delete Email** (`DeleteEmailConnections`), **Archive Email** (`ArchiveEmailConnections`), **Move Email** (`MoveEmailConnections`, the message side), **Download Email/Attachments** (`DownloadEmailConnections`, `DownloadEmailAttachments`).
+- Legacy: `ForwardMail`, `ReplyToMail`, `DeleteMail`, `SetMailCategories`, `GetMail` with `EmailId` set.
+- **New Email Received** trigger (`NewEmailReceived`) — the by-ID fetch of the triggering email after the event fires (e.g., the message was deleted/moved between event delivery and the job picking it up).
+
+What can cause it:
+- **Message deleted or moved** between when the ID was captured and when the activity ran — including another process or an Outlook rule moving/purging it, or a trigger backlog processing stale events.
+- **Mailbox mismatch.** Outlook message IDs are mailbox-scoped: an ID captured from the user's own mailbox does not resolve against a shared mailbox, and vice versa. `ErrorInvalidMailboxItemId` is the explicit form; Graph may also return plain 404.
+- **Stale persisted ID.** An ID stored from a previous run (asset, queue item, file) no longer resolves — IDs can change when a message is moved between folders by some Exchange operations.
+- **Insufficient scope for the target mailbox.** Missing `Mail.ReadWrite.Shared` for shared-mailbox access can surface as 404 instead of 403.
+
+What to look for:
+- Where the message ID came from (which upstream activity/trigger, which mailbox, how long ago).
+- The mailbox the failing activity resolves to (`Account` / shared mailbox argument) vs. the mailbox the ID was captured from.
+
+> **Different cause, do not apply this playbook:**
+> - `The resource could not be found.` raised while resolving a mail **folder** (activities that take a `MailFolder` argument and no message ID) — use [mail-folder-not-found.md](./mail-folder-not-found.md).
+> - The same message on OneDrive/SharePoint activities — use [drive-item-not-found.md](./drive-item-not-found.md).
+
+## Resolution
+
+The error is unambiguous; no further investigation is needed. Stop the investigation and verify the message reference with the user:
+
+1. **Confirm the message still exists** — check the mailbox (including Deleted Items) for the message at the time of failure. A message deleted, archived, or moved by a rule between capture and use is the most common cause.
+2. **Confirm both operations target the same mailbox.** The activity that produced the ID and the activity that consumed it must resolve the same `Account` / shared mailbox. For `ErrorInvalidMailboxItemId` this is the confirmed cause — fix the mailbox argument, not the ID.
+3. **Do not persist message IDs across runs.** If the workflow stores IDs (assets, queues, files) and consumes them later, re-fetch the message by filter at consumption time instead.
+4. **For trigger runs:** if the triggering email is routinely gone by the time the job runs (rules, competing consumers), make the workflow tolerate the miss (Try/Catch with a business-exception path) or remove the competing automation.
+5. **For shared mailboxes:** confirm the connection/scope includes shared-mailbox access (`Mail.ReadWrite.Shared`) — a missing shared scope can surface as 404.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/request-throttled.md

@@ -0,0 +1,45 @@
+---
+confidence: high
+---
+
+# O365 — Throttling / rate limit (429)
+
+## Context
+
+What this looks like — the job faults after Microsoft Graph rate-limits the tenant/app/mailbox (HTTP 429). The message is one of:
+
+- `Too many requests.` — the canonical throttle signal. Surfaced after the underlying Microsoft Graph SDK's built-in retries (which honor the server's `Retry-After`) are exhausted.
+- `The app or user has been throttled.`
+- `(HTTP Status Code: TooManyRequests) Batching request failed with an unknown reason.` — a 429 on one sub-request inside a batched operation whose error body couldn't be parsed. The status renders as the name `TooManyRequests`, not the number `429`, so don't pattern-match on the digits in this batching message.
+- A raw Microsoft Graph throttling message surfaced verbatim from a batched sub-response (when its error body *can* be parsed).
+
+> **Version note:** the friendly `Too many requests.` mapping for the SDK's "retries exhausted" condition (`tooManyRetries`) was added in package **3.10**. On **3.9.11** and earlier, that condition is **not** remapped — it surfaces as a raw Graph/HTTP throttle message via the generic-error fall-through instead. On older packages, match the raw throttle wording (and the 429 status) as well. Legacy (non-Connections) activities likewise surface this class as a raw `Microsoft.Graph.ServiceException` with Graph's own throttle wording rather than the friendly sentence.
+
+What activities can produce this:
+- **Any** Mail, Files/OneDrive, or Excel Online activity, but it is **far more likely** under high call volume — **For Each File/Folder** (`ForEachFileFolderConnections`), **For Each Email** (`ForEachEmailConnections`), **Bulk Add List Items** (`BulkAddListItemsConnections`), retrieve-all reads (e.g. **Get Email List** (`GetEmailListConnections`) with `MaxResults = 0`), or any loop/bulk path that issues many Graph calls in a short window.
+
+What can cause it:
+- **Microsoft Graph rate limit exceeded.** Per-app, per-mailbox, or per-tenant limits were hit. Graph returns 429 with a `Retry-After`; the Microsoft Graph SDK's built-in retries (not this activity package) respect it but eventually give up, and the throttle message is what you see.
+- **High call volume amplifies it.** Large `For Each` loops, bulk operations, retrieve-all, and request batching pack many calls together and reach the limit quickly.
+
+What to look for:
+- The failure follows a burst of operations (a big loop, a bulk action, many sequential calls), and the same workflow may succeed when re-run later or with less data.
+
+> **Different cause, do not apply this playbook:**
+> - 404/409 resource errors (`The resource could not be found.`, `The specified item name already exists.`) — these are deterministic, tied to a specific resource and fixed by correcting the locator or conflict behaviour, not by slowing down. Use the not-found / name-conflict playbooks.
+> - `The server is unable to process the current request.` (503) or request timeouts — service/transport transients, not rate limiting. Use **transient-service-error**.
+> - `The app or user has exceeded the allowed quota.` — a storage/quota limit, not a rate limit. Don't route it here; it isn't fixed by backing off.
+
+## Investigation
+
+1. Confirm the message is one of the throttle patterns above, and check whether it followed a high-volume step (large `For Each`, bulk, retrieve-all, or batched call).
+
+## Resolution
+
+There is no resource argument to fix — 429 is a transient, volume-driven limit. Reduce the call rate so the workflow stays under Microsoft Graph's threshold:
+
+- **Throttle the volume:** add a short delay between iterations, lower parallelism/concurrency, process fewer items per run, and narrow filters / lower `MaxResults` / `Top` so fewer calls are made.
+- **Honor `Retry-After` with backoff:** wrap the throttled operation in a Retry scope that waits and re-tries (exponential backoff). Re-run failed work after the suggested wait rather than immediately.
+- **Spread the load:** stagger scheduled jobs so multiple processes don't hit the same tenant/app simultaneously.
+
+If volume is already modest and `Retry-After`-respecting backoff still 429s, the limit is being consumed elsewhere — escalate (another process/app sharing the tenant or app registration, or a tenant-wide throttling event).

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/send-mail-rejected.md

@@ -0,0 +1,52 @@
+---
+confidence: medium
+---
+
+# O365 Mail — Send / forward / reply rejected
+
+## Context
+
+What this looks like — a Mail write operation (send, forward, reply) faults on the message itself rather than on authentication or folders. The message is one of:
+
+- `File does not exist: <path>` — a configured attachment path was not found on the runtime machine. Package-fixed text; surfaces as a raw `System.IO.FileNotFoundException` from legacy `SendMail`/`ForwardMail`, wrapped in `Office365Exception` on Connections activities.
+- A raw Microsoft Graph rejection surfaced verbatim — these are **Graph's own wording, not fixed package strings; match on the error-code family and the theme, not exact text**:
+  - `ErrorInvalidRecipients` / invalid-recipient wording — a recipient address is malformed or rejected.
+  - `ErrorSendAsDenied` / send-as wording — the authenticated user may not send as the configured `From` / shared mailbox.
+  - `ErrorMessageSizeExceeded` / size wording — the message (body + attachments) exceeds the Exchange size limit.
+
+On legacy activities these arrive as raw `Microsoft.Graph.ServiceException` (message embeds `Code: <errorCode>`); on Connections activities as `Office365Exception` with the Graph message preserved.
+
+What activities can produce this error:
+- **Send Email** (`SendMailConnections`), legacy **Send Mail** (`SendMail`).
+- **Forward Email** (`ForwardEmailConnections`), legacy **Forward Mail** (`ForwardMail`).
+- **Reply To Email** (`ReplyToEmailConnections`), legacy **Reply To Mail** (`ReplyToMail`).
+
+What can cause it:
+- **Malformed or rejected recipient** — typo in an address, a stray separator producing an empty entry, or a recipient the tenant rejects.
+- **Shared-mailbox send without Exchange rights.** Sending with a shared mailbox / `From` address requires the Exchange **Send As** (or **Send on Behalf**) permission for the authenticated user — the Graph scope `Mail.Send.Shared` alone is not enough.
+- **Attachment file missing on the runtime machine** — the path is valid at design time but absent where the job runs (user-profile paths, unmapped shares).
+- **Message too large** — attachments push the message over the Graph/Exchange limit.
+
+What to look for:
+- The recipient lists (`To`/`Cc`/`Bcc`), `From`/shared-mailbox argument, and attachment paths from the workflow source.
+- Whether the same send works without attachments, without the shared `From`, or with a single known-good recipient — isolates which input is rejected.
+
+> **Different cause, do not apply this playbook:**
+> - `The caller doesn't have permission to perform the action.` (403) — Graph-scope permission, use [insufficient-graph-scope.md](./insufficient-graph-scope.md).
+> - Token / `AADSTS` / not-authenticated messages — use [authentication-token-invalid.md](./authentication-token-invalid.md).
+> - `(HTTP Status Code: <status>) Batching request failed with an unknown reason.` — a batched sub-request failed without a parseable body; route by the embedded status per [transient-service-error.md](./transient-service-error.md) / [request-throttled.md](./request-throttled.md).
+
+## Investigation
+
+1. Classify the message: attachment path (`File does not exist`), recipient (`ErrorInvalidRecipients`), send-as (`ErrorSendAsDenied`), or size (`ErrorMessageSizeExceeded`).
+2. For recipient errors: read the exact `To`/`Cc`/`Bcc` values from the workflow source (or the composing variables) and look for malformed entries — empty strings from a trailing separator, missing `@domain`, display names without addresses.
+3. For send-as errors: capture the authenticated principal (connection UPN / scope account) and the configured `From`/shared mailbox; check in Exchange admin whether the principal holds Send As on that mailbox.
+4. For attachment errors: check the path exists **on the machine the job runs on**, under the robot's user profile.
+5. For size errors: total the attachment sizes; compare against the tenant's message size limit.
+
+## Resolution
+
+- **If malformed recipient:** fix the address list — remove empty entries, correct the address; when lists are built dynamically, validate each entry before the send.
+- **If send-as denied:** grant the authenticated user **Send As** (or **Send on Behalf**) on the shared mailbox in Exchange admin, and keep the shared-mailbox argument consistent with that grant. Re-run after Exchange permission propagation.
+- **If attachment missing:** correct the path or stage the file on the runtime machine; avoid user-profile-relative paths for unattended runs.
+- **If message size exceeded:** reduce attachment payload (compress, split across emails) or share a OneDrive link instead of attaching.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/transient-service-error.md

@@ -0,0 +1,48 @@
+---
+confidence: medium
+---
+
+# O365 — Transient service error / timeout (5xx)
+
+## Context
+
+What this looks like — the job faults on a server-side or transport-level failure that is generally **not** caused by the workflow configuration. The message is one of:
+
+- `The server is unable to process the current request.` — Microsoft Graph service unavailable (HTTP 503).
+- `Request time out.`
+- A raw inner message surfaced verbatim from a 500 / 504 or an HTTP request timeout (e.g. a `TaskCanceledException` / `HttpRequestException` message).
+- `There was an error on the email server. Please try modifying your Query or Top values to continue.` — a Mail read (**Get Email List** (`GetEmailListConnections`), **Get Email By Id** (`GetEmailByIdConnections`)) caught a Microsoft Graph error whose code is `UnknownError` (keyed on the Graph error code, **not** a specific HTTP status); the advice is to narrow the query / lower `Top`.
+- `(HTTP Status Code: <status>) Batching request failed with an unknown reason.` — a sub-request inside a batched operation failed (any non-success status — 5xx, or even 4xx / 429) and its error body couldn't be parsed.
+- `Automation Cloud cannot be reached. It may be a network fluctuation on the Runtime machine.` — the Runtime machine couldn't reach the connection service.
+
+What activities can produce this:
+- **Any** Mail, Files/OneDrive, or Excel Online activity — the failure originates at the Microsoft Graph service or the network path, which every activity shares. Legacy (non-Connections) activities surface the same class as a raw `Microsoft.Graph.ServiceException` / HTTP exception with the raw wording rather than the friendly sentence.
+
+What can cause it:
+- **Transient Microsoft Graph service errors** — 503 service-unavailable, 500 internal error, 504 gateway timeout. These usually clear on their own.
+- **Request / transport timeout** — the HTTP call exceeded its timeout (slow Graph response, large payload, or a network stall).
+- **Network fluctuation** reaching Automation Cloud / the connection service from the Runtime machine.
+- **(Mail only) a too-broad query or a transient server-side error** surfaces the Graph `UnknownError` advisory above (narrow the query / lower `Top`). A genuinely *malformed* OData filter is a different, deterministic error — `Invalid Query. Please use OData format for filter queries. Press F1 for examples.` — not a transient, so it doesn't belong in this playbook; use [mail-invalid-odata-query.md](./mail-invalid-odata-query.md).
+
+What to look for:
+- Intermittence — the same workflow succeeds on a later run. A consistent, repeatable failure usually points elsewhere (auth, scope, or a real not-found), not a transient.
+- Design-time note: a transient failure while a Studio file/folder picker loads surfaces as `The items could not be retrieved...` in the picker (re-open it to retry) — that is the picker's own error, not the activity's runtime fault.
+
+> **Different cause, do not apply this playbook:**
+> - `Too many requests.` / `The app or user has been throttled.` (429) — rate limiting, not a service/transport error. Use **request-throttled**. (Exception: inside a *batched* operation, a throttled sub-request whose body can't be parsed can surface the same `Batching request failed with an unknown reason` text as a 5xx — check the embedded status code, not the sentence alone.)
+> - 401 / 403 / 404 messages — authentication, permission, or not-found; these are deterministic, not transient. Use the matching playbook.
+
+## Investigation
+
+1. Read the exact message and decide whether it is intermittent (service/transport transient) or consistent (look elsewhere).
+2. Re-run the workflow. If it now succeeds, the cause was transient and the fix is a retry strategy.
+3. If the message is the Mail `... modify your Query or Top values ...` text, review the activity's filter/query and `Top`/`MaxResults`.
+4. If `Automation Cloud cannot be reached`, check the Runtime machine's network connectivity to Automation Cloud.
+
+## Resolution
+
+- **Transient 503 / 500 / 504 / timeout:** retry with backoff — wrap the operation in a Retry scope (a few attempts with increasing waits). These failures typically clear without any configuration change.
+- **Mail `modify your Query or Top values`:** simplify or correct the filter query and reduce `Top` / `MaxResults` so the server can process the request.
+- **Network (`Automation Cloud cannot be reached`):** restore connectivity on the Runtime machine and re-run.
+
+If a 503 / timeout reproduces consistently across retries over a sustained period, it is no longer transient — escalate (a Microsoft 365 service incident, or a proxy/firewall on the Runtime machine blocking Graph).

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/upload-file-quota-or-size.md

@@ -0,0 +1,47 @@
+---
+confidence: medium
+---
+
+# O365 Files — Upload quota, size, or session failure
+
+## Context
+
+What this looks like — an upload to OneDrive/SharePoint faults on storage limits or the chunked upload session. Friendly forms (`Office365Exception`, Connections activities):
+
+- `The user has reached their quota limit.` — Graph `QuotaLimitReached`: the target OneDrive/SharePoint storage is full.
+- `Max file size exceeded.` / `Maximum stream size exceeded.` — the file exceeds the service's per-file limit.
+- `Upload session failed.` / `Upload session incomplete.` / `Upload session not found.` — the chunked upload session for a large file broke mid-transfer (network interruption, session expiry) or could not be completed.
+
+Legacy `UploadFile` surfaces the same conditions as a raw `Microsoft.Graph.ServiceException` with Graph's own wording (message embeds the Graph error code, e.g. `Code: quotaLimitReached`) — match on the code/theme, not the friendly sentence. Verified raw over-size form: `Code: invalidRequest` / `The payload of the request was too large` with `Inner error: Code: maxFileSizeExceeded` — rejected at upload-session creation from the file's declared size, before any bytes are transferred.
+
+What activities can produce this error:
+- **Upload Files** (`UploadFilesConnections`), legacy **Upload File** (`UploadFile`).
+- Attachment uploads on Mail/Calendar writes use the same upload-session mechanics for large attachments and can fault with the session messages.
+
+What can cause it:
+- **Target storage full** — the user's OneDrive or the SharePoint site collection hit its quota. Deterministic until space is freed; not fixed by retrying.
+- **File over the per-file limit** — exceeds the Graph/SharePoint maximum upload size.
+- **Interrupted upload session** — transient network failure or timeout during a large chunked upload; the session expires or loses chunks. Usually clears on retry.
+
+What to look for:
+- Target drive's free space and the file's size — distinguishes the deterministic limits from the transient session failures.
+- Whether the failure repeats with the same file (limit) or only intermittently / for large files on slow links (session).
+
+> **Different cause, do not apply this playbook:**
+> - `Too many requests.` / `The app or user has been throttled.` — rate limiting, not storage; use [request-throttled.md](./request-throttled.md). The quota message here is a **storage** limit and is explicitly NOT a throttle — backing off does not fix it.
+> - `The specified item name already exists.` — name conflict; use [item-name-already-exists.md](./item-name-already-exists.md).
+> - `The resource could not be found.` — destination folder doesn't resolve; use [drive-item-not-found.md](./drive-item-not-found.md).
+> - Local source path missing on the runtime machine — surfaces as a local file-not-found, not a Graph error; fix the source path. Note: `UploadFilesConnections` skips empty files with a warning rather than faulting.
+
+## Investigation
+
+1. Classify the message: quota, per-file size, or upload session.
+2. For quota: check the target OneDrive / SharePoint site storage usage (site admin or OneDrive UI) — confirm it is at/near the limit.
+3. For size: get the file's size and compare against the service's per-file upload maximum.
+4. For session failures: check whether the failure reproduces — re-run once; correlate with network interruptions on the runtime machine and with file size (only large files use chunked sessions).
+
+## Resolution
+
+- **If quota reached:** free storage in the target OneDrive/site (empty recycle bin — items there still count), raise the site's storage quota, or upload to a different drive. Re-run after space is available.
+- **If file too large:** compress or split the file, or store it where the limit allows and share a link instead.
+- **If upload session failed/incomplete/not found:** transient — retry the upload (wrap in a Retry scope with backoff). If it reproduces consistently for the same large file, investigate the runtime machine's network stability (proxy idle timeouts on long uploads) before escalating.