@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-troubleshoot/references/activity-packages/mail-activities/playbooks/get-outlook-mail-failures.md

@@ -0,0 +1,109 @@
+---
+confidence: medium
+---
+
+# Get Outlook Mail Messages Failures
+
+## Context
+
+A `UiPath.Mail.Outlook.Activities` `Get Outlook Mail Messages` (`GetOutlookMailMessages`) activity reads messages from a folder of the **locally installed Outlook desktop application** through COM interop — it does not call a mail API. It resolves the `MailFolder` (and optional `Account`) against the Outlook profile of the Windows user the Robot runs as, optionally narrows the result with a `Filter` (DASL/Jet) and `Top` / `OnlyUnreadMessages`, and returns the matching `MailMessage` list. Failures cluster around **folder resolution** (the `MailFolder` / `Account` string), **volume / timeout** (`TimeoutMS` vs folder size), the **COM session** (Outlook installed + running + same privilege level), the **`Filter` syntax**, and **Cached Exchange Mode** sync (items that exist in Outlook but are not in the local cache).
+
+This activity shares the desktop-COM surface with `Send Outlook Mail Message` — Outlook-not-running / not-registered / bitness and privilege issues are diagnosed the same way (see [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 1). What is specific to `Get` is **folder resolution**, the **`Filter`** expression, and **Cached Exchange Mode** desync. For unattended / server-side mail with no desktop Outlook, prefer the modern Graph **o365-activities** (`Get Newest Email`, folder-scoped reads).
+
+What this looks like — Get Outlook Mail faults surface as one of these signatures:
+
+- `The specified folder does not exist` (the configured `MailFolder` could not be resolved) — branch 1.
+- `The operation has timed out` after `TimeoutMS` while pulling the message list — branch 2.
+- `The Outlook application is not running` / a COM cast failure, or the activity **freezes** with no exception — branch 3.
+- The activity throws on an invalid `Filter`, or returns **zero results** while a `Filter` is set even though matching mail exists — branch 4.
+- **No exception**, but the activity silently misses recent (or older) messages that are clearly visible in the Outlook desktop client — branch 5.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Folder not resolved (`MailFolder` / `Account`).** The `MailFolder` string does not map to a real Outlook folder. Common reasons: **nested-folder syntax** — a backslash path like `Inbox\Invoices` fails on some Mail-package versions (target the top-level `Inbox` first, or use the absolute form `\\your-email@domain.com\Inbox\Invoices`); **shared / generic mailbox** — reading from a shared box requires its primary address in the `Account` field (leaving `Account` blank uses only the default profile); **language discrepancy** — the folder name must match the Outlook UI language exactly (e.g. `Posteingang`, not `Inbox`, on a German client).
+2. **Timeout on a large folder.** The folder holds thousands of messages (or messages with massive attachments), so enumerating them exceeds `TimeoutMS` (default `30000` = 30 s) and Outlook lags.
+3. **Outlook not running / COM session broken.** The activity needs the desktop Outlook **installed and initialized** in the Robot's session. On a fully **unattended / RDP** session the foreground COM connection can intermittently drop, or there is no running Outlook instance; a **privilege mismatch** (UiPath running elevated/as Administrator while Outlook runs as a normal user, or vice versa) makes Windows block the two processes from talking — surfacing as "Outlook is not running" or a freeze. (Install / registration / bitness problems are the same surface as `Send Outlook Mail` branch 1.)
+4. **Malformed `Filter` (DASL / Jet).** The `Filter` property expects valid DASL/Jet query syntax. An unescaped or unquoted value (`[Subject] = VarSubject`) is invalid and the activity errors or returns zero results; the value must be single-quoted (`[Subject] = 'Text'`).
+5. **Cached Exchange Mode desync.** With **Cached Exchange Mode** on and the **Offline Settings** slider restricted (e.g. "Mail to keep offline: 3 months"), messages outside that window are not in the local `.ost` cache, so the activity cannot see mail the user can see in the full client — **no error**, just missing results.
+
+What to look for:
+
+- **The exception text (or its absence).** "specified folder does not exist" → branch 1; "operation has timed out" → branch 2; "Outlook is not running" / COM cast / a hang → branch 3; a `Filter`-related error or zero-results-with-a-filter → branch 4; **no error but missing recent/old mail** → branch 5.
+- **`MailFolder` + `Account`** (literal values, from `Main.xaml`) — the folder string (nested? absolute? localized?) and whether `Account` is set for a shared mailbox.
+- **Folder volume and `Top` / `OnlyUnreadMessages` / `TimeoutMS`** — the message count in the target folder vs the timeout and `Top`. Load-bearing for branch 2.
+- **Session type and privilege** — attended vs unattended/RDP, whether a desktop Outlook is running for the Robot's user, and whether UiPath and Outlook run at the **same privilege level**. Load-bearing for branch 3.
+- **The `Filter` string** — DASL/Jet validity and value quoting. Load-bearing for branch 4.
+- **Cached Exchange Mode state** — whether the account uses Cached Exchange Mode and how the Offline Settings slider is set. Load-bearing for branch 5 (and only verifiable on the host).
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error (or confirm there is none), the activity config, and the host.** From `uip or jobs get <job-key> --output json` → `Info`: the exception class and message, or note that the job ended without one. From workflow source (`.xaml`): the `Get Outlook Mail Messages` node — `MailFolder`, `Account`, `Filter`, `Top`, `OnlyUnreadMessages`, `TimeoutMS`. From the job: the Robot **host** and whether the run was **attended or unattended**.
+
+2. **Branch the diagnostic on the signature.**
+   - `The specified folder does not exist` → branch 1; go to step 3.
+   - `The operation has timed out` → branch 2; go to step 4.
+   - `Outlook is not running` / COM cast / a hang → branch 3; go to step 5.
+   - `Filter` error, or zero results with a `Filter` set → branch 4; go to step 6.
+   - No error but mail visible in the client is missing from the output → branch 5; go to step 7.
+
+3. **Confirm branch 1 (folder not resolved).** Compare the literal `MailFolder` against the real Outlook folder tree for the target account. Check for a backslash nested path (`Inbox\Invoices`), whether the source is a **shared mailbox** (then `Account` must carry its address), and whether the folder name matches the **Outlook UI language**. Any of these mismatches confirms the branch.
+
+4. **Confirm branch 2 (timeout on volume).** Read `TimeoutMS` and estimate the target folder's message count / attachment size. A 30 s default against a folder with thousands of messages (or large attachments) confirms the branch — especially when `Top` is high or unset and `OnlyUnreadMessages` is off.
+
+5. **Confirm branch 3 (Outlook session / privilege).** Confirm the run is unattended/RDP and whether a desktop Outlook is running for the Robot's user, and compare the **privilege level** of UiPath vs Outlook. "Outlook is not running" / a freeze on an unattended host, or an elevation mismatch, confirms the branch. (For an install/registration/bitness cast error, follow [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 1.)
+
+6. **Confirm branch 4 (filter syntax).** Read the `Filter` string. An unquoted value (`[Subject] = VarSubject`) or otherwise non-DASL/Jet syntax confirms the branch. Reproduce by removing the filter — if results return, the filter was the problem.
+
+7. **Confirm branch 5 (Cached Exchange Mode desync).** Only when there is **no error** but expected messages are absent. Check (on the host) whether the account uses Cached Exchange Mode and how the Offline Settings slider is set; mail outside the cached window being missing confirms the branch.
+
+The root cause must name **which of the five surfaces** the failure maps to, with the specific evidence: the exception text (or its absence), the `MailFolder`/`Account`/`Filter`/`Top`/`TimeoutMS` values, the session type and privilege, and the Cached Exchange Mode state. A generic "couldn't read mail" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Folder not resolved:**
+  - For a **nested** folder, target the top-level folder first, or use the **absolute path** form: `\\your-email@domain.com\Inbox\Invoices` (rather than `Inbox\Invoices`, which fails on some Mail-package versions).
+  - For a **shared / generic mailbox**, set the shared box's primary address in the **`Account`** field. Leave `Account` blank only to use the default Outlook profile.
+  - Match the folder name to the **exact Outlook UI language** (e.g. `Posteingang` on a German client, not `Inbox`).
+
+- **Branch 2 — Timeout on a large folder:**
+  - Raise `TimeoutMS` above the worst observed enumeration time (it is in **milliseconds**: `60000` = 60 s).
+  - Reduce the batch: set `Top` to a small number (e.g. `10`–`20`) instead of a high/unset value, and turn on **`OnlyUnreadMessages`** when read mail does not need parsing.
+  - For a chronically huge folder, narrow with a `Filter` (branch 4) or migrate the read to the modern Graph **o365-activities**, which paginate server-side.
+
+- **Branch 3 — Outlook session / privilege:**
+  - Ensure a desktop Outlook is **running and initialized** in the Robot's session before the activity — e.g. a `Start Process` on `outlook.exe` immediately before the mail activity to guarantee a valid foreground instance.
+  - Run UiPath (Studio/Robot) and Outlook at the **same privilege level** — both elevated or both normal — so Windows does not block the cross-process COM call.
+  - For install / registration / bitness errors, see [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 1; for unattended reliability, prefer the modern Graph **o365-activities** (no desktop dependency).
+
+- **Branch 4 — Malformed `Filter`:**
+  - Use valid DASL/Jet syntax and **single-quote** the value. Incorrect: `[Subject] = VarSubject`. Correct: `[Subject] = 'Text to find'`. With a variable: `"[Subject] = '" + mySubjectVariable + "'"`.
+  - Validate the filter against a small known-matching set before running at scale.
+
+- **Branch 5 — Cached Exchange Mode desync:**
+  - In Outlook: `File > Account Settings > Account Settings > (select account) > Change > Offline Settings`. Move the **"Mail to keep offline"** slider to **All**, or temporarily turn **off Cached Exchange Mode**, then re-run to confirm the missing messages now pass through.
+  - If turning the cache off fixes it, either keep it off for the Robot's profile or widen the cached window to cover the mail the automation must read.
+
+## Anti-patterns (what NOT to do)
+
+- **"Just raise `TimeoutMS` until it works."** A bigger timeout helps a genuinely large folder (branch 2) but does nothing for a folder that does not resolve (branch 1), a broken COM session (branch 3), a bad filter (branch 4), or a cache desync (branch 5). Confirm the branch first.
+- **"Wrap Get Outlook Mail in a Try Catch and continue on empty."** Swallowing the error (or an empty result) turns a folder-resolution / filter / cache problem into downstream logic processing **zero** messages as if the mailbox were empty — a silent wrong result that is harder to find than the original fault.
+- **"Run UiPath as Administrator to fix the COM error."** Elevation does not fix COM interop and often **breaks** it by creating a privilege mismatch with a normally-launched Outlook (branch 3). Match privilege levels instead.
+- **"Use Get Outlook Mail Messages on an unattended server with no Outlook."** The activity requires the desktop client and a profile; for headless / unattended reads use the modern Graph **o365-activities** instead.
+
+## Prevention (cross-branch)
+
+- Address folders with the absolute `\\account\Inbox\Sub` form (and set `Account` for shared mailboxes), and keep folder names in the Outlook UI language — verify at design time, not at first failure.
+- Bound every read with a sensible `Top` / `OnlyUnreadMessages` / `Filter` so a folder-size spike cannot time the activity out.
+- For unattended automation, default to the modern Graph **o365-activities**; reserve the Outlook COM read for attended desktop automations, and keep UiPath and Outlook at the same privilege level.
+- Parameterize and single-quote every `Filter` value; never concatenate an unquoted variable into a DASL/Jet expression.
+- Set the Robot profile's Cached Exchange Mode window to cover the mail the automation must read (or disable the cache for that profile).
+
+## Related
+
+- [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) — the outbound Outlook COM activity; shares the COM-not-running / not-registered / bitness / privilege surface (branch 3 here) and the SMTP/Graph fallback guidance.
+- [o365-activities overview](../../o365-activities/overview.md) — modern Microsoft Graph / OAuth mail reads (`Get Newest Email`, folder-scoped reads); the preferred path for unattended mail and the destination when migrating off the COM read activity.
+- [mail-activities overview](../overview.md) — the package's connection model (Outlook desktop COM vs SMTP/protocol).

package/skills/uipath-troubleshoot/references/activity-packages/mail-activities/playbooks/move-outlook-mail-failures.md

@@ -0,0 +1,97 @@
+---
+confidence: medium
+---
+
+# Move Outlook Mail Message Failures
+
+## Context
+
+A `UiPath.Mail.Outlook.Activities` `Move Outlook Mail Message` (`MoveOutlookMessage`) activity moves a `MailMessage` into a destination `MailFolder` of the **locally installed Outlook desktop application** through COM interop — it does not call a mail API. It runs under the Outlook profile of the Windows user the Robot runs as, resolves the destination folder (and optional `Account`), and moves the supplied message item. Failures cluster around the **COM session** (Outlook running/synced, especially unattended), the **destination folder path / `Account`**, a **modern-vs-classic type mismatch** after a package update, and the **New Outlook** client removing the desktop COM API the activity depends on.
+
+Move shares the desktop-COM surface with the other Outlook activities — Outlook-not-running / session-drop is diagnosed like [get-outlook-mail-failures.md](./get-outlook-mail-failures.md) branch 3 and [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 1, and the folder-resolution rules match [get-outlook-mail-failures.md](./get-outlook-mail-failures.md) branch 1. What is distinctive here is the **classic-vs-modern Move activity type mismatch** and the **New Outlook** regression. For unattended / server-side mail with no desktop Outlook, prefer the modern Graph **o365-activities** Move Email.
+
+What this looks like — Move Outlook Mail Message faults surface as one of these signatures:
+
+- `The operation failed.` or `The specified folder does not exist` that is **intermittent**, or fails 100% on **unattended/Production** robots — branch 1.
+- `The folder does not exist` that fails **immediately, every run**, in attended testing — branch 2.
+- `Cannot convert type 'String' to 'IResource'` / `... to 'Office365Message'` (a design-time/binding/cast error) after a dependency update — branch 3.
+- The automation **broke completely after a system/Office update**, with COM-bind / "Outlook is not running" style errors on a machine that now runs **New Outlook** — branch 4.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **COM session loss (Outlook not running / not synced).** The Robot's COM session cannot reach a live local Outlook instance, so the folder tree cannot be indexed. Causes: Outlook is closed, asleep, or running on a **detached unattended Windows profile**; the connection drops intermittently mid-run. Hallmark: the same workflow that works attended fails on unattended/Production, or fails only on *some* runs.
+2. **Destination folder path / `Account` mismatch.** The `MailFolder` string does not resolve. Causes: a **nested** destination addressed by a bare leaf name (`Archive`) instead of a path (`Inbox\Archive`); a **shared / secondary mailbox** destination without the mailbox's address in the `Account` field. Hallmark: fails immediately and deterministically, every run, even attended.
+3. **Modern-vs-classic type mismatch.** After updating dependencies, the workflow mixes the **modern** Move Email activity (newer `UiPath.Mail.Activities` / `UiPath.MicrosoftOffice365.Activities`) — which expects an object reference (`IResource` / `Office365Message`) for the message and/or folder — with a **string** message-ID or folder-path variable wired in from the classic design. Surfaces as a `Cannot convert type 'String' to 'IResource' / 'Office365Message'` binding/cast error.
+4. **New Outlook (desktop COM API removed).** The host updated to Microsoft's **New Outlook** (the web-hybrid client), which **removes the Outlook Desktop COM API** that all `UiPath.Mail.Outlook.Activities` rely on. The classic activity can no longer bind to an Outlook COM server. Hallmark: the automation worked, then broke **completely** right after a Windows/Office update flipped the machine to New Outlook.
+
+What to look for:
+
+- **The exception text and timing** — intermittent / unattended-only "operation failed" / "folder does not exist" → branch 1; immediate-and-deterministic "folder does not exist" → branch 2; a `String`→`IResource`/`Office365Message` cast/binding error → branch 3; "broke completely after an update" with COM-bind failures → branch 4.
+- **Session type and Outlook state** — attended vs unattended/RDP, and whether a desktop Outlook is running/synced for the Robot's user. Load-bearing for branches 1 and 4.
+- **The destination `MailFolder` + `Account`** (literal values from `Main.xaml`) — nested path? shared mailbox? Load-bearing for branch 2.
+- **Which Move activity and how its inputs are typed** — classic `Move Outlook Mail Message` (`MoveOutlookMessage`, string/`MailMessage` inputs) vs the modern Move Email (`IResource`/`Office365Message`), and whether a `String` is wired where a resource object is expected. Load-bearing for branch 3.
+- **Outlook client variant on the host** — Classic Outlook vs New Outlook, and whether a recent update flipped it. Load-bearing for branch 4 (only verifiable on the host).
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, activity, host, and timing.** From `uip or jobs get <job-key> --output json` → `Info`: the exception class and message. From workflow source (`.xaml`): the Move activity — classic `MoveOutlookMessage` vs the modern Move Email, the destination `MailFolder` / `Account`, and how the message and folder inputs are typed (string vs resource). From the job: the Robot **host**, whether the run is **attended or unattended**, and whether failures are **intermittent or 100%**.
+
+2. **Branch the diagnostic on the signature + timing.**
+   - Intermittent, or unattended-only, "operation failed" / "folder does not exist" → branch 1; go to step 3.
+   - Immediate, deterministic "folder does not exist" → branch 2; go to step 4.
+   - `Cannot convert type 'String' to 'IResource' / 'Office365Message'` → branch 3; go to step 5.
+   - "Broke completely after an update", COM-bind failure → branch 4; go to step 6.
+
+3. **Confirm branch 1 (COM session loss).** Confirm the run is unattended/RDP and whether a desktop Outlook is running and synced for the Robot's Windows user. Intermittency, or works-attended-fails-unattended, with no folder-path problem, confirms the branch. (Install/registration/bitness is the same surface as [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 1.)
+
+4. **Confirm branch 2 (folder path / `Account`).** Read the literal destination `MailFolder`. A bare nested-folder leaf name (`Archive` instead of `Inbox\Archive`), or a shared-mailbox destination with an empty `Account`, confirms the branch — especially when it fails deterministically on every run, attended included.
+
+5. **Confirm branch 3 (type mismatch).** Identify which Move activity is used and how its message/folder inputs are bound. A `String` variable wired into a modern activity input that expects an `IResource` / `Office365Message` object — surfacing as the cast/convert error after a recent dependency update — confirms the branch.
+
+6. **Confirm branch 4 (New Outlook).** Determine the Outlook client variant on the host and whether a recent update flipped it to **New Outlook**. A complete, post-update break with COM-bind failures on a host now running New Outlook confirms the branch (the desktop COM API the activity needs is gone).
+
+The root cause must name **which of the four surfaces** the failure maps to, with the specific evidence: the exception text and its timing/determinism, the session type and Outlook state, the destination `MailFolder`/`Account`, the activity variant and input typing, and the Outlook client variant. A generic "move failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — COM session loss:**
+  - Keep a live Outlook instance available to the Robot: leave a foreground Classic Outlook window open on the target machine during the run, and add Outlook to the **Startup apps** for the Robot's Windows user so it launches and syncs on logon.
+  - Wrap the move in a **Retry Scope** with a short (2–3 s) delay — intermittent COM sync losses often clear on the second attempt.
+  - For unattended/Production reliability, prefer the modern Graph **o365-activities** Move Email (no desktop dependency).
+
+- **Branch 2 — Folder path / `Account`:**
+  - Address a nested destination by its path, not a bare leaf name: `Inbox\Archive` (or `Inbox/Archive`), not `Archive`.
+  - For a shared / secondary mailbox destination, set the mailbox's full email address in the activity's **`Account`** field.
+
+- **Branch 3 — Modern-vs-classic type mismatch:**
+  - In a **modern** Move Email activity, do not hardcode a string message-ID / folder path. Use the **`+` (plus) button** next to the folder/message property to map the target via the directory picker so it resolves to the expected `IResource` / `Office365Message` object.
+  - Or, if your variables are explicit `String` / `MailMessage` types, use the **classic** `Move Outlook Mail Message` (`MoveOutlookMessage`) activity, which accepts them directly. Do not mix classic string inputs into modern resource-typed properties.
+
+- **Branch 4 — New Outlook:**
+  - Toggle the host's Outlook back to **Classic Outlook** (the switch in the upper-right corner of the Outlook window) so the desktop COM API the activity needs is present again.
+  - If the machine must stay on **New Outlook**, stop using the `UiPath.Mail.Outlook.Activities` desktop activities entirely and migrate the workflow to the modern Microsoft 365 Integration activities (**`UiPath.MicrosoftOffice365.Activities`**, covered by [o365-activities](../../o365-activities/overview.md)), which use the Graph API over a web connection rather than local desktop COM.
+
+## Anti-patterns (what NOT to do)
+
+- **"Add a longer Delay / more Retry Scope passes until it works."** Retry helps a genuinely intermittent COM sync loss (branch 1). It will never fix a wrong folder path (branch 2), a type mismatch (branch 3), or a host on New Outlook (branch 4) — it just burns time and masks the real cause.
+- **"Wrap Move in a Try Catch and continue."** Swallowing the failure leaves the message unmoved while downstream logic assumes it was filed — a silent data-handling bug. Use Try-Catch only with a real recovery path (retry the transient COM state, route the item, or re-throw).
+- **"Force-fit a string into the modern Move Email property."** Hardcoding a string where an `IResource` / `Office365Message` is expected is exactly branch 3 — map the resource with the `+` picker, or use the classic activity.
+- **"Reinstall Office / downgrade the package to fix the post-update break."** If the host flipped to New Outlook (branch 4), neither helps — toggle back to Classic Outlook or move to the Graph activities.
+
+## Prevention (cross-branch)
+
+- For unattended / server-side mail moves, default to the modern Graph **o365-activities** Move Email; reserve the classic desktop Move for attended automations with a live, synced Outlook.
+- Provision Robot hosts with a running, logged-in Classic Outlook (Startup apps) and pin the machine to **Classic Outlook** so a New-Outlook flip cannot silently break the COM activities.
+- Address destination folders by path (`Inbox\Archive`) and set `Account` for shared-mailbox destinations at design time.
+- Keep classic and modern Move activities separate — match input types (string/`MailMessage` for classic; `IResource`/`Office365Message` for modern) and re-validate bindings after any `UiPath.Mail.Activities` upgrade.
+
+## Related
+
+- [get-outlook-mail-failures.md](./get-outlook-mail-failures.md) — the inbound read activity; shares the COM-session (branch 3 there) and folder-resolution (branch 1 there) surfaces.
+- [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) — the outbound activity; shares the COM-install / not-running / privilege surface (branch 1 there).
+- [o365-activities overview](../../o365-activities/overview.md) — modern Microsoft Graph / OAuth mail (Move Email and folder-scoped ops); the required path when the host runs New Outlook and the preferred path for unattended moves.
+- [mail-activities overview](../overview.md) — the package's connection model (Outlook desktop COM vs SMTP/protocol).

package/skills/uipath-troubleshoot/references/activity-packages/mail-activities/playbooks/send-outlook-mail-failures.md

@@ -0,0 +1,95 @@
+---
+confidence: medium
+---
+
+# Send Outlook Mail Message Failures
+
+## Context
+
+A `UiPath.Mail.Outlook.Activities` `Send Outlook Mail Message` (`SendOutlookMail`) activity does **not** call a mail API — it drives the locally installed **Outlook desktop application** through COM interop. It attaches to (or launches) `OUTLOOK.EXE` under the Windows user the Robot runs as, composes the message through the Outlook Object Model using that user's mail profile, and returns once Outlook accepts the item. Failures therefore originate at one of three surfaces: the **COM layer** (Outlook installed/registered, process bitness, orphaned process), the **session/UI** (a prompt or Work Offline state blocking the call), or the **inputs** (uninitialized `To`/`Subject`/`Body`, or a bad attachment path).
+
+Because the call goes through a desktop application, the Outlook COM activities are fragile on **unattended** Robots, where there is no interactive desktop to dismiss a prompt and the profile may not be configured for the Robot's Windows user. When Outlook is not a hard requirement, the **Send SMTP Mail Message** activity (`UiPath.Mail.SMTP.Activities`) or the modern Graph **o365-activities** are the more reliable path (see Resolution → alternative).
+
+What this looks like — Send Outlook Mail faults surface as one of these signatures:
+
+- `System.InvalidCastException: Unable to cast COM object of type '...' to interface type '...'` or `System.Runtime.InteropServices.COMException: Library not registered. (REGDB_E_CLASSNOTREG / TYPE_E_LIBNOTREGISTERED)` — branch 1.
+- The activity blocks and then fails with a **timeout** (`TimeoutMS` elapsed), or the job hangs with no exception — branch 2.
+- `System.NullReferenceException: Object reference not set to an instance of an object` raised at the activity — branch 3.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **COM cast / library not registered.** The Outlook COM server cannot be bound. Causes: Outlook is **not installed** on the Robot host (the activity needs the desktop client, not just an account); a **bitness mismatch** between the Robot/process and the installed Outlook (a 64-bit process against a 32-bit Outlook, or vice versa); a **corrupted Office registry / type library** (common after a botched Office update); or an **orphaned `OUTLOOK.EXE`** from a prior run holding the COM server in a bad state.
+2. **Activity times out or hangs.** The COM call is blocked waiting on something the Robot cannot satisfy. Causes: the Outlook **security prompt** ("A program is trying to send an email message on your behalf…", the Outlook Object Model Guard) is foregrounded but invisible/unanswered — fired when antivirus is out of date / not registered with Windows Security Center or programmatic-access policy is not set; Outlook is in **Work Offline** mode so the send never completes; or a slow first **profile load** exceeds the activity's `TimeoutMS` (default `30000` = 30 s).
+3. **Uninitialized input.** A variable bound to `To`, `Subject`, or `Body` is `Nothing`/null (an upstream step that should have populated it was skipped or scoped wrong), or an attachment path in the `Attachments`/`Files` collection is empty/null. The activity dereferences it and throws `Object reference not set to an instance of an object`.
+
+What to look for:
+
+- **The exception class and message** — first signal. `Unable to cast COM object` / `Library not registered` → branch 1; a timeout / hang with no inner exception → branch 2; `NullReferenceException` at the activity → branch 3.
+- **Outlook install + bitness on the Robot host** — whether the **desktop** Outlook is installed on the machine that ran the job (not the dev machine), and its bitness vs the Robot process (`File > Account > About Outlook` shows 32-/64-bit). Load-bearing for branch 1.
+- **Session type (attended vs unattended) and Outlook state** — whether a security prompt or Work Offline state could be blocking the send, and whether the Robot's Windows user even has a configured Outlook profile. Load-bearing for branch 2.
+- **The `To`/`Subject`/`Body` and attachment inputs** — literal vs expression-bound; trace each variable's producer and scope, and whether attachment paths resolve. Load-bearing for branch 3.
+- **`TimeoutMS`** on the activity (milliseconds; default `30000`) — relevant to branch 2.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, activity, and host.** From `uip or jobs get <job-key> --output json` → `Info`: the exception class and full message (including the inner exception). From workflow source (`.xaml`): the `Send Outlook Mail Message` node — literal vs expression-bound `To`/`Subject`/`Body`, the `Attachments` collection, the `Account`/profile, and `TimeoutMS`. From the job: the Robot **host** and whether the run was **attended or unattended**.
+
+2. **Branch the diagnostic on the signature.**
+   - `Unable to cast COM object` / `Library not registered` (`REGDB_E_CLASSNOTREG` / `TYPE_E_LIBNOTREGISTERED`) → branch 1; go to step 3.
+   - Timeout / hang with no clean inner exception → branch 2; go to step 4.
+   - `NullReferenceException` at the activity → branch 3; go to step 5.
+
+3. **Confirm branch 1 (COM cast / library not registered).** Confirm the desktop Outlook is installed on the **Robot host** (not only the developer machine) and note its **bitness** against the Robot process. A 64-bit process with a 32-bit-only Outlook (or a corrupted type library after an Office update) produces the cast / not-registered error. Check for a stray `OUTLOOK.EXE` left running with no window from a prior job.
+
+4. **Confirm branch 2 (timeout / hang).** Determine whether the run is **unattended** (no interactive desktop). Check whether the Outlook **security prompt** could be firing (antivirus state / programmatic-access policy), whether Outlook is in **Work Offline** mode, and whether the Robot's Windows user has a configured profile. Read `TimeoutMS` and compare against a realistic profile-load + send time. A hang on an unattended Robot with no visible Outlook is the prototypical case.
+
+5. **Confirm branch 3 (uninitialized input).** In the workflow source, trace the variables bound to `To`, `Subject`, `Body`, and each attachment path back to their producers. A variable left `Nothing` (upstream step skipped, or declared in an inner scope) or an empty attachment path confirms the branch. Reproduce by hardcoding literal values into the activity fields — if the error disappears, an input was null.
+
+The root cause must name **which of the three surfaces** the failure maps to, with the specific evidence: the exception text, the Outlook install/bitness on the Robot host, the session type and Outlook state, and the input values. A generic "Outlook failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — COM cast / library not registered:**
+  - Ensure the **desktop Outlook is installed** on every Robot host that runs the process (the activity cannot work against a webmail-only account).
+  - Match **bitness** — the installed Outlook must match the Robot process architecture. Re-install the matching-bitness Office, or set the project compatibility so the process matches the installed Outlook.
+  - Repair the Office installation: close **both** UiPath (Studio/Robot) and Outlook, run a **Quick Repair** of Microsoft Office (`Windows Settings > Installed apps > Microsoft Office > Modify > Quick Repair`), then restart the host.
+  - Clear any orphaned `OUTLOOK.EXE` before the run (Task Manager / `Stop-Process -Name OUTLOOK -Force` as the Robot's Windows user) and fix whatever leaves it orphaned.
+
+- **Branch 2 — Activity times out or hangs:**
+  - Make sure Outlook is **running, signed in, and Online** (turn off `Send/Receive > Work Offline`) under the Robot's Windows user before the activity runs.
+  - Resolve the **security prompt** at its source rather than waiting on it: keep antivirus up to date and registered with Windows Security Center (this is what normally suppresses the Object Model Guard prompt), or set the Outlook programmatic-access / Trust Center policy via Group Policy for the Robot's user. Do **not** rely on a human dismissing the prompt on an unattended Robot.
+  - If the send is **legitimately** slow (first profile load), raise `TimeoutMS` above the worst observed duration (it is in **milliseconds**: `60000` = 60 s). Raising the timeout does **not** fix a blocking security prompt or Work Offline state — only branch-2 *slowness*.
+
+- **Branch 3 — Uninitialized input:**
+  - Initialize every variable bound to `To`, `Subject`, and `Body` before the activity, and guard against null/empty (a null `To` is the most common). Validate it by hardcoding literal values into the fields first.
+  - Ensure each attachment path in the `Attachments`/`Files` collection is non-empty and resolves to an existing file at runtime; drop the attachment input entirely when there is nothing to attach rather than passing an empty string.
+
+### Alternative — bypass Outlook with SMTP or modern Graph
+
+If the COM/interop errors persist (or the process runs **unattended**), avoid the Outlook desktop dependency entirely:
+
+- **Send SMTP Mail Message** (`UiPath.Mail.SMTP.Activities`) — sends straight to your mail server; no Outlook install or profile needed. Configure the SMTP host (e.g. `smtp.office365.com`), port (`587` with STARTTLS), and credentials.
+- **Modern Graph** — the **o365-activities** (`UiPath.MicrosoftOffice365.Activities`) send mail via OAuth-authenticated Microsoft Graph, with no desktop client. Prefer these for server-side / unattended automation.
+
+## Anti-patterns (what NOT to do)
+
+- **"Just raise `TimeoutMS` until it works."** A larger timeout only helps a *legitimately slow* send (branch 2). For a blocking security prompt or Work Offline state it just makes the Robot hang longer before failing — fix the prompt/offline state instead.
+- **"Wrap Send Outlook Mail in a Try Catch and continue."** Swallowing the exception turns a non-sent email into a silent success; downstream logic assumes the mail went out. Use Try-Catch only with a real recovery path (retry a transient COM state, fall back to SMTP, mark the item Failed, or re-throw).
+- **"Disable the Outlook security prompt by lowering Programmatic Access to 'Never warn me'."** Doing this by hand on each host is brittle and a security regression; the supported fix is up-to-date antivirus registered with Windows Security Center, or a Group Policy for the Robot's user.
+- **"Use Send Outlook Mail on an unattended server with no Outlook."** The activity requires the desktop client and a profile; on headless/unattended hosts use **Send SMTP Mail Message** or the modern Graph **o365-activities** instead.
+
+## Prevention (cross-branch)
+
+- For unattended / server-side mail, default to **Send SMTP Mail Message** or the modern Graph **o365-activities** — reserve the Outlook COM activities for attended desktop automations that genuinely need the user's Outlook.
+- Provision every Robot host that uses the Outlook activities with a **matching-bitness desktop Outlook** and a configured profile for the Robot's Windows user; verify at provisioning, not at first failure.
+- Keep antivirus current and registered with Windows Security Center (or set the programmatic-access Group Policy) so the Object Model Guard prompt never fires unattended.
+- Initialize and validate `To`/`Subject`/`Body` and attachment paths before the activity; never pass an empty attachment path.
+
+## Related
+
+- [o365-activities overview](../../o365-activities/overview.md) — modern Microsoft Graph / OAuth mail (no desktop Outlook); the preferred path for unattended mail and the destination when migrating off the COM activities.
+- [mail-activities overview](../overview.md) — the package's connection model (Outlook desktop COM vs SMTP/protocol) and how to choose between them.

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

@@ -0,0 +1,8 @@
+# Mail Activities Playbooks
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Send Outlook Mail Message Failures | Medium | `Send Outlook Mail Message` (`SendOutlookMail`, `UiPath.Mail.Outlook.Activities`) fails across three surfaces: COM cast / library-not-registered (`Unable to cast COM object` / `Library not registered` — Outlook not installed/registered, process-vs-Outlook bitness mismatch, corrupted Office registry, or orphaned `OUTLOOK.EXE`); activity times out or hangs (hidden "a program is trying to send an email" security prompt, Work Offline mode, or slow profile load); and `Object reference not set to an instance of an object` from an uninitialized `To`/`Subject`/`Body` or empty attachment path. Includes the `Send SMTP Mail Message` / modern Graph fallback for unattended runs. | [send-outlook-mail-failures.md](./playbooks/send-outlook-mail-failures.md) |
+| Get Outlook Mail Messages Failures | Medium | `Get Outlook Mail Messages` (`GetOutlookMailMessages`, `UiPath.Mail.Outlook.Activities`) fails across five surfaces: folder not resolved (`The specified folder does not exist` — nested-path backslash syntax, shared mailbox needing the `Account` field, or a localized folder name); timeout on a large folder (`The operation has timed out` — raise `TimeoutMS`, lower `Top`, enable `OnlyUnreadMessages`); Outlook not running / COM session or privilege mismatch (`The Outlook application is not running` / freeze on unattended RDP, or a UiPath-vs-Outlook elevation mismatch); malformed DASL/Jet `Filter` (unquoted value yields an error or zero results); and Cached Exchange Mode desync (no error, but recent/old mail visible in the client is missing). Shares the COM surface with Send Outlook Mail; cross-references the modern Graph o365 reads for unattended runs. | [get-outlook-mail-failures.md](./playbooks/get-outlook-mail-failures.md) |
+| Move Outlook Mail Message Failures | Medium | `Move Outlook Mail Message` (`MoveOutlookMessage`, `UiPath.Mail.Outlook.Activities`) fails across four surfaces: COM session loss (`The operation failed` / `The specified folder does not exist` — intermittent or 100% on unattended robots when Outlook is closed/asleep/detached; fix with a live foreground Outlook, Startup apps, and a Retry Scope); destination folder path / `Account` mismatch (deterministic `The folder does not exist` — use `Inbox\Archive` not `Archive`, set `Account` for shared mailboxes); modern-vs-classic type mismatch (`Cannot convert type 'String' to 'IResource' / 'Office365Message'` after a dependency update — map the resource with the `+` picker, or use the classic activity with string/`MailMessage` inputs); and the New Outlook regression (a system update flips the host to New Outlook, which removes the Desktop COM API — toggle back to Classic Outlook or migrate to the Graph o365 Move Email). | [move-outlook-mail-failures.md](./playbooks/move-outlook-mail-failures.md) |
+| Delete Outlook Mail Message Failures | Medium | `Delete Outlook Mail Message` (`DeleteOutlookMailMessage`, `UiPath.Mail.Outlook.Activities`) fails across five surfaces: stale message reference (`The operation failed. An object could not be found.` — the item was moved/deleted between Get and Delete; fetch-then-delete promptly + Try Catch); collection modified in loop (`Collection was modified; enumeration operation may not execute.` — deleting inside a `For Each` over the live message list; iterate a `.ToList()` copy / backwards, or Move-then-delete); New Outlook regression (removes the Desktop COM API — revert to Classic or migrate to Graph); COM session blocked / privilege (`The operation has timed out` / freeze from a modal programmatic-access dialog or a UiPath-vs-Outlook elevation mismatch; match privilege, fix Trust Center); and mailbox permission / access denied (Robot account lacks Full Access on a shared mailbox; set `Account` and grant Full Access via Exchange). | [delete-outlook-mail-failures.md](./playbooks/delete-outlook-mail-failures.md) |

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

@@ -5,6 +5,8 @@
 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.MicrosoftOffice365.Activities.Mail.MoveEmailConnections`). Modern connections activities and legacy activities (`MoveMail`, `DownloadFile`, `CreateFolder`, `UploadFile`, `CreateWorkbook`, `AddSheet`) sometimes share display names but run different code paths — treat them as different.
+- **Display names are narrative, not evidence** — activity display names, process names, and workflow comments describe intent; they must never confirm or eliminate a hypothesis. Decide from status codes, error codes, logs, traces, and live probes. (Repro/test workflows in particular carry display names that assert a cause; weigh only the recorded behavior.)
+- **Exception type routes the code path** — modern `*Connections` activities and triggers wrap every failure in `UiPath.MicrosoftOffice365.Office365Exception` with a friendly message; a **raw** `Microsoft.Graph.ServiceException`, `ArgumentNullException`, `NullReferenceException`, or `FileNotFoundException` therefore always means a **legacy** activity (no wrapper; raw ServiceException messages embed `Code: <graphErrorCode>` plus the same sentence the friendly mapping uses — match the sentence). A raw `UiPath.ConnectionClient.Contracts.ConnectionHttpException` means the failure happened at the Integration Service connection layer (trigger event/sample lookup or token fetch), not at Microsoft Graph; the wrapped form preserves its message verbatim.
 - **Connection / Microsoft 365 account** — the Integration Service connection in evidence authenticates against the same Microsoft 365 user principal the user is asking about. Different connections = different mailboxes, different OneDrive scopes, different SharePoint sites = unrelated data.
 - **Mailbox in scope** — for Mail activities, confirm the resolved mailbox is the one the user is asking about. The same connection can target the user's own mailbox, a shared mailbox, or a delegated mailbox via the activity argument; Outlook IDs are mailbox-scoped, so an item that resolves in one mailbox will not resolve in another.
 - **Target resource** — the resource identifier in evidence matches the one the user reports: mail folder ID or path, message ID, OneDrive/SharePoint item ID or URL or drive-relative path, drive ID, SharePoint site URL plus document library, workbook file name, sheet name. Don't substitute a similarly-named resource.
@@ -17,6 +19,27 @@ If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy.
 
 1. **Activity execution traces** — these activities emit per-call traces. Pull them when available — they expose the exact Microsoft Graph endpoint hit, request/response status, and timing. Trace evidence narrows whether the failure originated at connection resolution, OAuth token validation, the Graph call, or post-processing inside the activity.
 
+## Cross-Cutting Error Classes
+
+Many Microsoft Office 365 failures are **not specific to one activity** — they come from the shared authentication + Microsoft Graph layer and can surface from *any* Mail / Files / Excel activity. The user-visible text is keyed off the **Microsoft Graph error code, not the HTTP status**: some codes surface a fixed UiPath message, others surface the raw Graph message verbatim. So **match on the message text**, and when the class is cross-cutting, investigate the connection / permission / rate / configuration rather than over-focusing on the faulted activity's own arguments.
+
+Route by message:
+
+- Token / `AADSTS` / `not authenticated` / cancelled login / `No default connection` / `Automation Cloud cannot be reached` → [authentication-token-invalid](./playbooks/authentication-token-invalid.md) (401).
+- `The caller doesn't have permission ...` / `Access restricted to the item's owner.` / raw `Insufficient privileges ...` → [insufficient-graph-scope](./playbooks/insufficient-graph-scope.md) (403). Note Graph may instead return **404** for unauthorized cross-mailbox/shared access — that path is the not-found playbooks.
+- `Too many requests.` / `The app or user has been throttled.` / batched 429 → [request-throttled](./playbooks/request-throttled.md) (429).
+- `The server is unable to process the current request.` / `Request time out.` / 500 / 504 / batched 5xx → [transient-service-error](./playbooks/transient-service-error.md).
+- Faults **before any Graph call** (`Could not retrieve the selected asset`, `You must provide a value for ...`, `Please select an account.`, placement errors) → [application-scope-misconfigured](./playbooks/application-scope-misconfigured.md).
+- Raw `ConnectionHttpException` (or `Office365Exception` with the identical IS-status message) from a trigger → [email-trigger-connection-event-failure](./playbooks/email-trigger-connection-event-failure.md).
+- `The specified object was not found in the store.` / `Item ... doesn't belong to the targeted mailbox` / 404 on a message ID → [mail-message-not-found](./playbooks/mail-message-not-found.md).
+- `Invalid Query. Please use OData format for filter queries. Press F1 for examples.` → [mail-invalid-odata-query](./playbooks/mail-invalid-odata-query.md).
+- `File does not exist: <path>` / `ErrorInvalidRecipients` / `ErrorSendAsDenied` / `ErrorMessageSizeExceeded` on a send/forward/reply → [send-mail-rejected](./playbooks/send-mail-rejected.md).
+- `Value cannot be null. (Parameter 'DriveItem')` from legacy Copy Item → [copy-item-argument-null](./playbooks/copy-item-argument-null.md).
+- Raw `NullReferenceException` from a legacy Mail activity → [legacy-mail-null-reference](./playbooks/legacy-mail-null-reference.md).
+- `Folder path must contain at least one segment.` / segment whitespace / `'<segment>' is a file, not a folder.` / `Value cannot be null. (Parameter 'Folder name'/'Folder path'/'Parent folder')` → [create-folder-invalid-path](./playbooks/create-folder-invalid-path.md).
+- `Folders cannot be downloaded with this activity ...` / `Cannot convert the item into PDF format ...` / `Local File Path should point to a folder or directly to a .pdf file.` → [download-file-conversion-or-destination](./playbooks/download-file-conversion-or-destination.md).
+- `The user has reached their quota limit.` / `Max file size exceeded.` / `Upload session failed/incomplete/not found.` → [upload-file-quota-or-size](./playbooks/upload-file-quota-or-size.md) (quota is storage, **not** 429 throttling).
+
 ## Testing Prerequisites
 
 When testing hypotheses for Microsoft Office 365 Activities issues, gather and verify these before drawing conclusions:

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

@@ -39,12 +39,21 @@ Failures can originate at any of those layers — connection resolution (Integra
 - **Filter returns no matching email** — Mailbox contains zero messages matching the configured filter at the moment the activity runs. `Get Newest Email` throws `Office365Exception: No email matching the filter criteria, received in the last 1 hour has been found...` synchronously.
 - **Mail folder not found** — Mail activity (`MoveEmailConnections`, `GetNewestEmail`, `GetEmailListConnections`, `ForEachEmailConnections`, `WaitForEmailReceived`, `NewEmailReceived` trigger, legacy `MoveMail`) cannot resolve the configured `MailFolder`. Surfaces as one of: `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>.`.
 - **Local-filesystem name conflict on download** — `DownloadEmailConnections` or `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 because two attachments on the same email resolve to the same local filename. Conflict is on the local filesystem, not in OneDrive/SharePoint.
+- **Message not found** — message-by-ID activity (forward, reply, mark, delete, archive, download, get-by-ID) cannot resolve the message: deleted/moved, or the mailbox-scoped ID was used against a different mailbox. Surfaces as `The resource could not be found.`, raw `ErrorItemNotFound`, or `ErrorInvalidMailboxItemId`.
+- **Invalid OData filter query** — `Invalid Query. Please use OData format for filter queries. Press F1 for examples.` from `GetMail` / `GetNewestEmail` / list-and-iterate reads with a malformed `$filter`.
+- **Send rejected** — invalid recipient, shared-mailbox send without Exchange Send As rights, message size exceeded (raw Graph wording), or `File does not exist: <path>` for a missing attachment.
+- **Trigger connection event failure** — `NewEmailReceived` / `EmailSent` faults at the Integration Service connection layer (`ConnectionHttpException`, raw or wrapped) while fetching the event email, debug sample, or token.
+- **Raw NullReferenceException from a legacy Mail activity** — null `Message` input or null recipient-array element dereferenced before the Graph call; raw NRE type always indicates a legacy activity.
 
 ### Files (OneDrive / SharePoint)
 
 - **404 — file or folder not found** — Files activity fails to resolve the configured ID, URL, path, or browse selection because the Drive item was deleted, moved out of scope, or is not accessible to the connection. Surfaces as `Office365Exception: The resource could not be found.` or as the wrapping form `Cannot find item configured with connection <connection> at path <path>.`
 - **Item name already exists** — Files write activity (`CreateFolderConnections`, `CopyItemConnections`, `MoveItemConnections`, `RenameItemConnections`, `UploadFilesConnections`) throws `Office365Exception: The specified item name already exists.` when the destination already contains an item with the target name and `ConflictBehavior = Fail`. Affects legacy activities equivalents as well (`CreateFolder`, `UploadFile`).
 - **Local-filesystem name conflict on download** — `DownloadFileConnections` throws `Office365Exception: Multiple items with the name <name> found in the specified folder.` when the **local** destination folder already contains a file with that name and `ConflictResolution = Fail`. Conflict is on the local filesystem, not in OneDrive/SharePoint.
+- **Create Folder invalid name/path** — `CreateFolderConnections` rejects its own input: null name/path/parent, empty or whitespace-padded path segments, or an intermediate path segment that exists as a file.
+- **Download conversion or destination error** — folder bound where a file is required, unsupported PDF-conversion source extension, non-`.pdf` export destination, or unresolvable shared-item parent drive.
+- **Upload quota / size / session failure** — target storage full (`The user has reached their quota limit.`), file over the per-file limit, or a chunked upload session broken mid-transfer.
+- **Null `DriveItem` input on legacy Copy Item** — raw `ArgumentNullException: Value cannot be null. (Parameter 'DriveItem')` when an upstream search matched nothing.
 
 ### Excel
 

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/application-scope-misconfigured.md

@@ -0,0 +1,49 @@
+---
+confidence: medium
+---
+
+# O365 — Application Scope / connection misconfiguration (before any Graph call)
+
+## Context
+
+What this looks like — the failure happens **before any Microsoft Graph call**, from the Microsoft 365 Application Scope's own configuration (no HTTP status / Graph error code). **Where** it shows up depends on the fault:
+
+**As a faulted Orchestrator job (runtime):**
+- `Could not retrieve the selected asset: '<asset>'` — the scope reads its connection from an Orchestrator asset that can't be retrieved (the inner cause can be a missing / forbidden asset, or an empty asset id).
+- A bare `ArgumentNullException` naming a credential field (e.g. `ApplicationId`) — a required credential resolved to null at runtime. (The friendly "You must provide a value …" wording below is design-time only.)
+
+**As Studio design-time validation / test-connection errors (not a job fault):**
+- `You must provide a literal value for <field> in order to use design time services` — a required field is bound to an expression the design-time service can't read (Classic design experience).
+- `The authentication parameters could not be read` — the connection object is null/empty.
+- `You must provide a value for <field>` or `You must provide a value for at least one of the following properties: <Application Secret, Secure Application Secret>` / `<Password, Secure Password>` — a required credential field for the chosen authentication type is missing.
+- `Please select an account.` — Interactive Token auth with no account chosen.
+- `Activity is only valid inside an Office 365 Scope` (Mail / Excel / SharePoint) **or** `Cannot be used outside of a MicrosoftOffice365 Application Scope or outside of a Use OneDrive/SharePoint activity` (Files/OneDrive) — the activity was placed outside any Application Scope.
+
+What activities can produce this:
+- The **Microsoft 365 Application Scope** (`Office365ApplicationScope`) itself, and every Mail / Files / Excel activity placed under it (the fault propagates to the child that runs first, or surfaces as a design-time validation error on the misplaced activity).
+
+What can cause it:
+- **Orchestrator asset can't be retrieved** — the configured connection asset has the wrong name/path, isn't present in the folder the robot runs in, the robot lacks permission to read it, or it isn't a valid connection asset.
+- **Non-literal value on a design-time field** — a required scope field is bound to a variable/expression that can't be read at design time.
+- **Null / incomplete credentials** — no connection is configured, or the credential fields required by the chosen authentication type (App ID + Tenant + Secret/Certificate; Username + Password) are missing. At design time this is the `You must provide a value …` / `The authentication parameters could not be read` validation; at runtime a missing Application ID surfaces instead as a bare `ArgumentNullException` naming the field.
+- **No account selected** — Interactive Token auth without a chosen account.
+- **Activity placed outside the scope** — a Mail/Files/Excel activity dropped on the canvas with no Microsoft 365 Application Scope (or, for OneDrive/SharePoint, no Use OneDrive/SharePoint activity) as a parent.
+
+> **Different cause, do not apply this playbook:**
+> - Any message carrying a Microsoft Graph result — `The caller doesn't have permission ...` (403), `The resource could not be found.` (404), `Too many requests.` (429), `The server is unable to process the current request.` (503), or a token/`AADSTS` authentication error. Those happen **after** the scope successfully authenticates and makes a Graph call — use **insufficient-graph-scope**, the not-found playbooks, **request-throttled**, **transient-service-error**, or **authentication-token-invalid** respectively.
+
+## Investigation
+
+1. Read the message to identify which configuration family it is (asset / non-literal field / null or incomplete credentials / no account / placement).
+2. **Asset (`Could not retrieve the selected asset`):** confirm the asset exists in the folder the robot runs against and that the robot account can read it; check the asset name/path is correct.
+3. **Credentials (`You must provide a value for ...` / `The authentication parameters could not be read`):** confirm every field required by the scope's authentication type is set with a literal value.
+4. **Placement (`Activity is only valid inside an Office 365 Scope` / `Cannot be used outside ...`):** confirm the activity sits inside a Microsoft 365 Application Scope (or a Use OneDrive/SharePoint activity for OneDrive/SharePoint).
+
+## Resolution
+
+- **Asset:** correct the selected Orchestrator asset (right name/path), ensure it lives in the robot's folder, and grant the robot read access — or switch the scope to configure credentials directly.
+- **Non-literal field:** provide a literal value for the field the message names, or configure the scope so the design-time service can read it.
+- **Incomplete credentials:** supply the fields required for the chosen authentication type — Application ID + Tenant + (Secret or Certificate) for app-only, Username + Password for ROPC, or select an account for Interactive Token.
+- **Placement:** move the activity inside a Microsoft 365 Application Scope (or a Use OneDrive/SharePoint activity).
+
+This class is resolved entirely in Studio / Orchestrator configuration — there is no Graph response to handle. If the configuration is correct (asset resolves, credentials complete, activity correctly nested) and the scope still fails to build, escalate.

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/authentication-token-invalid.md

@@ -0,0 +1,53 @@
+---
+confidence: medium
+---
+
+# O365 — Authentication / token invalid (401)
+
+## Context
+
+What this looks like — the job faults the moment an Office 365 activity (or the Microsoft 365 Application Scope) tries to authenticate, before any business operation runs. The message is one of:
+
+- A raw Microsoft Graph authentication message surfaced verbatim — most often `Access token has expired or is not yet valid.` or similar wording mentioning an invalid/expired token. This is the typical token-expiry case.
+- `The caller is not authenticated.`
+- `Authentication failed.`
+- `Authentication was cancelled.`
+- `A configuration error AADSTS<code> occurred in the activity. For information on how to solve this, visit the page: https://docs.uipath.com/activities/other/latest/productivity/aadsts-errors` — an Entra ID (Azure AD) failure at token acquisition. The `AADSTS<code>` identifies the exact cause (e.g. `AADSTS65001` = admin consent not granted; `AADSTS700016`/`AADSTS7000215` = wrong app id/secret).
+- `Authentication attempt took longer than <N> seconds to complete, and was cancelled.` — an interactive sign-in that wasn't completed in time. This fires while *creating / adding* the connection (the interactive sign-in wizard, default 60s), not mid-run for an already-authenticated connection.
+- `The client did not complete the authentication after <N> seconds, and as a result the operation was canceled. Authentication type: InteractiveToken.` — an **Interactive Token** sign-in triggered *mid-run* (an activity needed a token and opened a browser/WAM sign-in) that nobody completed in the window (default 30s). This is the signature of Interactive Token running where no human can complete the prompt — most often an **unattended / Agent / StudioPro** job, or an attended run where the user never finished the sign-in.
+- `No default connection is available.`
+- `Automation Cloud cannot be reached. It may be a network fluctuation on the Runtime machine.`
+
+What activities can produce this:
+- **Any** Mail, Files/OneDrive, or Excel Online activity — they all authenticate through the same Microsoft 365 connection / Application Scope. Representative: **Send Mail** (`SendMailConnections`), **Get Email List** (`GetEmailListConnections`), **Get File List** (`GetFileListConnections`), **Upload File** (`UploadFilesConnections`), **Read Range** (`ReadRangeConnections`).
+
+What can cause it:
+- **Access token expired or invalid.** The cached token is no longer valid and could not be silently refreshed (refresh token expired, password changed, session revoked).
+- **Consent revoked or never granted.** The app registration lacks admin consent for a requested permission, surfaced as an `AADSTS` configuration error (commonly `AADSTS65001`).
+- **Interactive login timed out or was cancelled — usually the *symptom* of a wrong auth choice.** With Interactive Token auth a browser/WAM sign-in wasn't completed within the timeout. The timeout itself is the surface symptom; look one level up: **Interactive Token needs a human to complete the sign-in, so it is the wrong auth mode for an unattended / Agent / StudioPro job, or a scope with no bound account** — there the prompt can never be completed and every run times out. (An occasional attended run can succeed when a person happens to finish the sign-in, so a single past success doesn't make the mode viable for unattended use.)
+- **No connection / wrong connection.** No default Microsoft 365 connection is configured, or the selected connection has lost its authentication.
+- **Connection service unreachable.** The Runtime machine can't reach Automation Cloud (network fluctuation) to resolve the connection.
+
+> **Different cause, do not apply this playbook:**
+> - `The caller doesn't have permission to perform the action.` / `Access restricted to the item's owner.` / a raw `Insufficient privileges to complete the operation.` — the caller **is** authenticated but lacks the Graph permission for the operation. Use **insufficient-graph-scope**.
+> - Configuration faults that fire before authentication (`Could not retrieve the selected asset`, `You must provide a value for ...`, `Please select an account.`) — use **application-scope-misconfigured**.
+
+## Investigation
+
+1. Read the exact message and match it to one of the patterns above — the wording determines the fix path (token vs consent vs interactive-timeout vs connection vs network).
+2. If the message contains `AADSTS<code>`, note the code and look it up (the linked docs page maps each code to its cause). `AADSTS65001` = consent not granted; secret/cert/app-id codes = wrong or expired credentials.
+3. Identify the connection / Application Scope authentication type (Interactive Token, Integration Service connection, App ID + Secret/Certificate, Username/Password) — this determines how the token is obtained and how to renew it.
+4. **If the message is an interactive sign-in timeout** (`The client did not complete the authentication ...`), check the job's **execution context**: an unattended / Agent / StudioPro robot has no one to complete the browser/WAM prompt, so the timeout is structural (every run fails the same way) — the root cause is the auth mode, not the timeout value. An attended run could simply have had the user not finish the sign-in in time.
+5. Confirm whether the failure is permanent (token / consent / credential / auth-mode problem — fails every run) or intermittent (network reaching Automation Cloud — clears on retry).
+
+## Resolution
+
+- **If the token is expired/invalid:** re-authenticate the connection — re-run the interactive login, refresh/reconnect the Integration Service connection, or rotate and update the app secret/certificate that has expired.
+- **If `AADSTS65001` / consent:** have an administrator grant admin consent for the permissions the app registration requests.
+- **If another `AADSTS` credential code:** correct the Application ID / Tenant / secret / certificate to match the app registration.
+- **If an interactive sign-in timed out in an unattended / Agent / StudioPro context** (`The client did not complete the authentication after <N> seconds ... Authentication type: InteractiveToken.`): the root cause is the **auth mode**, not the timeout value. Switch the Microsoft 365 Scope to **app-only authentication (App ID + Secret or Certificate)** — the client-credentials flow needs no human — or route the connection through **Integration Service** (which refreshes the token). Selecting/binding an account only helps an *attended* desktop where a person completes the sign-in; it does **not** make Interactive Token viable for unattended/Agent runs, and raising the timeout won't help when no one is there to complete the prompt.
+- **If an interactive sign-in timed out on an attended desktop:** complete the browser/WAM sign-in within the timeout window on the next run.
+- **If `No default connection is available`:** select or configure a valid Microsoft 365 connection on the activity / Application Scope.
+- **If `Automation Cloud cannot be reached`:** transient network issue — verify the Runtime machine's connectivity to Automation Cloud and re-run.
+
+If the connection authenticates cleanly on its own (e.g. a test call succeeds) yet the activity still 401s, the cause is outside the activity — escalate (tenant-level conditional access, token lifetime policy, or a revoked session).

package/skills/uipath-troubleshoot/references/activity-packages/o365-activities/playbooks/copy-item-argument-null.md

@@ -0,0 +1,34 @@
+---
+confidence: high
+---
+
+# O365 Files — Copy Item null DriveItem input
+
+## Context
+
+What this looks like — the legacy **Copy Item** (`CopyItem`) activity faults with a raw:
+
+- `System.ArgumentNullException: Value cannot be null. (Parameter 'DriveItem')`
+
+The activity checks its `DriveItem` input at the start of execution and throws when the bound variable is `null`. Legacy activity — the exception escapes unwrapped.
+
+What can cause it:
+- **Upstream lookup matched nothing.** The variable bound to `DriveItem` is the output of an upstream `FindFilesAndFolders` / get-item activity that found no match — `FindFilesAndFolders` leaves its `First` output unset when the search returns zero results, so the variable stays `null`.
+- **Variable never assigned** — the output binding on the upstream activity is missing, or the assignment sits in a conditional branch that didn't run.
+
+What to look for:
+- Which variable is bound to the activity's `DriveItem` property, and which upstream activity is supposed to populate it.
+- Whether the upstream search criteria can legitimately match nothing for some inputs (intermittent fault = data-dependent empty result).
+
+> **Different cause, do not apply this playbook:**
+> - A null `Destination` / parent is **not** an error for this activity — it falls back to the OneDrive root. Only the `DriveItem` parameter faults.
+> - `Value cannot be null. (Parameter '<localized property name>')` from a **Connections** activity is a missing required input on that activity (wrapped form) — read that activity's configuration, e.g. [create-folder-invalid-path.md](./create-folder-invalid-path.md) for Create Folder.
+> - `The resource could not be found.` — the item reference was non-null but doesn't resolve; use [drive-item-not-found.md](./drive-item-not-found.md).
+
+## Resolution
+
+The error is unambiguous; the `DriveItem` input was `null` at runtime. Fix the producer, then guard:
+
+1. **Trace the variable bound to `DriveItem`** back to its producing activity and confirm the output binding is set and the producer actually ran before Copy Item.
+2. **If the producer is a search (`FindFilesAndFolders`):** the search matched nothing — verify the search folder, filename filter, and search mode against what's actually in OneDrive/SharePoint, and fix the criteria.
+3. **Add a null guard** (If `DriveItem Is Nothing`) between the lookup and Copy Item, handling the no-match case explicitly (skip, log, or business exception) instead of letting the copy fault.