@uipath/skills 1.196.0 → 1.197.0

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

@@ -17,12 +17,12 @@ Failures can originate at any of those layers — connection resolution (Integra
 ### Gmail
 
 - **Get Newest Email** (`GetNewestEmailConnections`) — retrieves the single most recent message matching a configured filter.
-- **Send / Reply / Forward Email** (`SendEmailConnections`, `ReplyToEmailConnections`, `ForwardEmailConnections`) — send, reply, or forward a Gmail message. Uploads attachments via Gmail multipart upload, so they share Drive-class quota failures.
+- **Send / Reply / Forward Email** (`SendEmailConnections`, `ReplyToEmailConnections`, `ForwardEmailConnections`, plus legacy `SendEmail`) — send, reply, or forward a Gmail message. Uploads attachments via Gmail multipart upload, so they share Drive-class quota failures. Legacy `SendEmail` validates each attachment path locally first (`File does not exist: <path>`) and requires at least one of `To`/`Cc`/`Bcc` unless `IsDraft`.
 
 ### Drive
 
 - **Item write operations** (`CreateFolderConnections`, `CopyFileConnections`, `MoveFileConnections`, `RenameFileFolderConnections`, `UploadFilesConnections`, `CreateSpreadsheetConnections`, `CreateDocumentConnections`) — create, copy, move, rename, or upload Drive items; behavior on duplicate name in the destination is governed by the `ConflictResolution` enum (`Replace`, `Fail`, `Rename`, `AddSeparate`, `UseExisting`).
-- **Item resolution by ID, URL, or path** (most Drive activities, e.g., `GetFileFolderConnections`, `GetFileFolderInfoConnections`, `DownloadFileConnections`, `DeleteFileOrFolderConnections`, `ShareFileFolderConnections`, plus the write operations above) — resolve a target file or folder against the Drive API; fails with HTTP 404 when the identifier no longer resolves.
+- **Item resolution by ID, URL, or path** (most Drive activities, e.g., `GetFileFolderConnections`, `GetFileFolderInfoConnections`, legacy `GetFileInfo`, `DownloadFileConnections`, `DeleteFileOrFolderConnections`, `ShareFileFolderConnections`, plus the write operations above) — resolve a target file or folder against the Drive API; fails with HTTP 404 when the identifier no longer resolves, or with `ArgumentOutOfRangeException` (`Could not extract an object Id from the Url ...`) before the call when a passed URL has no extractable ID.
 - **Upload Files** (`UploadFilesConnections`, legacy `UploadFile`) — upload local files into Drive via multipart upload; subject to user storage quota and shared-drive file-count limit.
 
 ### Sheets
@@ -35,12 +35,12 @@ Failures can originate at any of those layers — connection resolution (Integra
 
 ### Gmail
 
-- **Filter returns no matching email** — Gmail mailbox contains zero messages matching the configured filter at the moment the activity runs. `Get Newest Email` throws `GmailException: No email matching the search criteria has been found` synchronously, with no retry or wait.
+- **Filter returns no matching email** — Gmail mailbox contains zero messages matching the configured filter at the moment the activity runs. `Get Newest Email` throws `GmailException: No email matching the search criteria has been found` synchronously, with no retry or wait. The `NewEmailReceived` / `EmailSent` triggers, run in debug/test mode, throw the related `No email matching the filter criteria, received/sent in the last 1 hour has been found...`.
 
 ### Drive
 
 - **Item name conflict** — Drive write activity throws `GSuiteException: Multiple items with the name <name> found in the specified folder.` when the target folder already contains an item with that name and `ConflictResolution` cannot resolve the duplicate. Affects Create Folder, Copy File, Move File, Rename, Upload, Create Spreadsheet, and Create Document.
-- **404 — file or folder not found** — A Drive activity fails to resolve the configured ID, URL, or path because the resource was deleted, trashed, or is not accessible to the connection. Surfaces as one of: `File not found: <id>. [404]` (raw `Google.GoogleApiException`), `The service drive has thrown an exception. HttpStatusCode is NotFound. ...` (wrapped form), or `The resource was not found.` (translated form).
+- **404 — resource not found / item does not resolve** — An activity fails to resolve its configured target (Drive file/folder/spreadsheet/document by ID/URL/path, a Gmail message by ID, or a browser-selected item) because the resource was deleted, trashed, or is not accessible to the connection. Surfaces as one of: `File not found: <id>. [404]` (raw `Google.GoogleApiException`), `The service <svc> has thrown an exception. HttpStatusCode is NotFound. ...` (wrapped form), `The resource was not found.` (translated form), or ``Cannot find item configured with connection `<id>` [at path `<path>`].`` (browser-selected item).
 - **Upload storage quota or shared drive file limit exceeded** — Drive or Gmail attachment upload throws `GSuiteException: Upload failed after <N> bytes. ...` carrying a Google 403. Two underlying conditions: `storageQuotaExceeded` (user's Drive storage full) or `The file limit for this shared drive has been exceeded.` (shared drive at the 500K item cap). Affects `UploadFilesConnections`, legacy `UploadFile`, and Gmail send/reply/forward when the message has attachments.
 
 ### Sheets
@@ -49,6 +49,14 @@ Failures can originate at any of those layers — connection resolution (Integra
 - **10,000,000-cell limit exceeded** — Sheets write or grid-expand activity throws `GSuiteException` carrying a Google 400 BadRequest: `This action would increase the number of cells in the workbook above the limit of 10000000 cells.` The cap is the sum of the bounded grid (rows × columns) across every sheet in the spreadsheet, including empty cells. Hard Google quota; cannot be raised. Affects all cell-writing / grid-expanding Sheets activities.
 - **Invalid range — unable to parse** — Range-addressed Sheets activity throws `GSuiteException` carrying a Google 400 BadRequest: `Invalid data[0]: Unable to parse range: <SheetName>!<CellRef>`. Common causes: 1-indexing mistake (`A0`), empty/null range variable, sheet name with spaces or special characters not single-quoted in A1 notation, stale sheet reference after a rename, or off-by-one in a dynamically-built address. Affects all range-addressed Sheets activities.
 
+### Cross-cutting (any service)
+
+These families are not specific to one Google service — any activity can hit them, and the failing layer (not the activity) determines the fix.
+
+- **Connection / authentication / permission** — failure in the identity layers rather than the resource: an auth-phase `TimeoutException` (`Authentication attempt took longer than <N> seconds to complete, and was cancelled.`), an expired/invalid token (`Invalid authentication credentials.` / `Authentication error: the access token is expired or invalid.`), authorization denied (`Permission to the resource was denied.` / `The user does not have sufficient permissions for the file.` / domain policy), or a raw `ConnectionHttpException` when the Integration Service connection itself is unreachable/deleted (design-time browse failures carry `CNS1044`/`CNS1045`).
+- **Invalid or null input (client-side)** — the activity throws *before* any Google API call because an input is null, empty, out of range, or an invalid combination: `Value cannot be null. (Parameter '<x>')`, `The object used in the activity does not exist.` (mapped `NullReferenceException`), `Column not found: <name>`, `RelativeRowIndex/RelativeColumnIndex <i> outside the range: 0 to <n>.`, `Named ranges with cell value are invalid. Named ranges require no cell input.`, `<property> must be a positive number`, `You do not have the following labels`. The fix is in the workflow inputs, not the connection or resource.
+- **Transient / rate-limit / per-request timeout** — environmental and often temporary: Google 5xx (`Internal server error occurred. Please try again later.` / `The service is currently unavailable. Please try again later.`), rate/quota limits at 429 (`The daily limit was exceeded.` / `The user rate limit was exceeded.` / `The rate limit was exceeded.`), network faults (`HttpRequestException`), a per-request `RequestTimeout` overrun (`A task was canceled.` — a `TaskCanceledException`, **not** a `TimeoutException`), or the generic fallback `An error occurred in the activity.` when the underlying status matched no known mapping. Triggers auto-retry socket errors and 5xx with backoff before surfacing.
+
 ## Package
 
 NuGet: `UiPath.GSuite.Activities`

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/connection-and-auth-failures.md

@@ -0,0 +1,55 @@
+---
+confidence: medium
+---
+
+# GSuite — Connection, authentication, and permission failures
+
+## Context
+
+This playbook covers failures that originate in the identity/connection layers — Integration Service connection resolution, Google OAuth token validation, or Google-side authorization — rather than in the requested resource or the activity inputs. The fix is always about *who is connecting and what they are allowed to do*, never about the file/range/filter the activity targets.
+
+What this looks like — any of the following messages:
+
+- `Authentication attempt took longer than <N> seconds to complete, and was cancelled.` — a `System.TimeoutException` thrown while establishing the connection / acquiring the OAuth token, **not** while calling the Google API. This is the only place GSuite throws a real `TimeoutException`. `<N>` is the configured connection/auth timeout in seconds (legacy scope: the `TimeoutMS` property).
+- `Invalid authentication credentials.` — wrapped `GSuiteException`, Google API returned **HTTP 401** with no more specific reason. The access token presented to Google was rejected.
+- `Authentication error: the access token is expired or invalid.` — wrapped `GSuiteException`, Google error reason `authError`. Same root as 401: the token is no longer valid.
+- `Permission to the resource was denied.` — wrapped `GSuiteException`, Google API returned **HTTP 403** with no more specific reason. The token is valid but the account/connection is not authorized for this operation.
+- `The user does not have sufficient permissions for the file.` — wrapped `GSuiteException`, Google reason `insufficientFilePermissions`. The authenticated account lacks access to the specific Drive item.
+- `The domain administrators have disabled Drive apps.` — wrapped `GSuiteException`, Google reason `domainPolicy`. A Workspace admin policy blocks the connection's app.
+- A raw `UiPath.ConnectionClient.Contracts.ConnectionHttpException` (or a `GSuiteException` carrying its message verbatim) — the Integration Service connection layer itself failed when the activity tried to fetch a token: connection deleted after the workflow started, connection unreachable, token refresh rejected because the user revoked authorization. Legacy `GSuiteApplicationScope` activities using `IntegrationService` auth surface this raw at runtime.
+- ``Connection [<connectionId>] is invalid or you do not have access to it`` — wrapped `GSuiteException` (the `ConnectionHttpException` surfaced on the activity). The configured `ConnectionId` does not resolve to a connection the running identity can use: it was deleted/disabled, is owned in another folder/workspace, the robot account lacks permission to the connection's folder, or the project binding points at the wrong connection. Thrown during token acquisition, before any Google API call.
+
+**Design-time variant:** when picking a Drive/Sheets item in the Studio browse dialog fails with *"Items cannot be retrieved"*, the underlying cause is frequently a `ConnectionHttpException` with **HTTP 403** and code `CNS1044` (insufficient permissions) or `CNS1045` (insufficient folder permissions). This is the same authorization problem surfacing at design time instead of run time.
+
+What activities can produce these errors:
+Every `*Connections` activity (all Gmail, Drive, Sheets, Docs, Calendar, Tasks, Forms, Apps Script modern activities) and every legacy `GSuiteApplicationScope` child, because all of them resolve a connection and acquire a token before doing any work. Auth-timeout is most visible on the scope/connection itself and on the first activity to execute after a cold token.
+
+What can cause it:
+- **Expired or revoked token** (401 / `authError`): the connection's OAuth grant lapsed, the user changed their Google password, or authorization was revoked in the Google account's security settings.
+- **Insufficient scope / sharing** (403 / `insufficientFilePermissions`): the connection's OAuth scopes don't include the needed Drive/Gmail/Sheets scope, or the target resource was never shared with the authenticated account.
+- **Admin / domain policy** (`domainPolicy`): a Workspace administrator disabled third-party apps or the specific connector.
+- **Connection lifecycle** (raw `ConnectionHttpException`): the Integration Service connection was deleted, disabled, or is unreachable between scope setup and activity execution.
+- **Auth timeout** (`TimeoutException`): the OAuth flow or token exchange exceeded the configured timeout — slow network to Google's OAuth endpoint, an interactive consent prompt that was never completed, or a `TimeoutMS` set too low on a legacy scope.
+
+> **Different cause — do not apply this playbook:**
+> - **`The storage quota was exceeded.`** / **`Upload failed after <N> bytes. ...`** is also an HTTP 403, but it is a *quota* failure, not an authorization failure — use [upload-storage-quota-exceeded.md](./upload-storage-quota-exceeded.md).
+> - **`The resource was not found.`** (404) means the resource doesn't resolve, not that access was denied — use [drive-file-not-found.md](./drive-file-not-found.md).
+> - Transient 5xx / rate-limit / per-request timeout (`A task was canceled.`) → use [transient-and-timeout-errors.md](./transient-and-timeout-errors.md).
+
+## Investigation
+
+1. **Identify the failing layer from the message.** Auth-timeout text → token acquisition. 401 / `authError` → token rejected. 403 / `insufficientFilePermissions` / `domainPolicy` → authorization. Raw `ConnectionHttpException` → the IS connection itself.
+2. **Capture the connection** in evidence — the Integration Service connection name and the Google account email it authenticates as. Confirm the connection still exists and is enabled in Integration Service.
+3. **For 401 / auth errors:** check whether the connection's token can be refreshed — reconnect/re-authorize the connection and confirm it succeeds against Google.
+4. **For 403 / permission errors:** capture the target resource (Drive item, mailbox, spreadsheet) and confirm the authenticated account has access to it in the Google UI, and that the connection's OAuth scopes cover the operation.
+5. **For auth-timeout:** capture the configured timeout (`TimeoutMS` on a legacy scope) and whether the auth path requires interactive consent. Confirm network reachability to Google's OAuth endpoint from the robot.
+
+## Resolution
+
+- **If the token is expired or revoked (401 / `authError`):** Reconnect/re-authorize the Integration Service connection (or refresh the legacy scope's credential). Confirm the Google account password/2FA didn't change and that authorization wasn't revoked in the Google account security settings.
+- **If authorization is insufficient (403 / `insufficientFilePermissions`):** Grant the authenticated account access to the target resource, or recreate the connection with the OAuth scopes the operation requires (e.g., full Drive scope rather than read-only). For the design-time `CNS1044`/`CNS1045` browse failure, the same scope/permission grant fixes the picker.
+- **If a domain policy blocks the app (`domainPolicy`):** Escalate to the Google Workspace administrator to allow the connector/app.
+- **If the connection itself failed (raw `ConnectionHttpException`):** Confirm the connection exists and is enabled in Integration Service; recreate it if it was deleted. Verify the robot has network reachability to the connection service.
+- **If authentication timed out:** Confirm network reachability and latency to Google's OAuth endpoint. Raise the legacy scope's `TimeoutMS` if the auth path is legitimately slow; for interactive OAuth, ensure the consent flow can complete in the robot's session (unattended robots cannot answer an interactive prompt).
+
+If the connection reconnects cleanly, the account demonstrably has access, and the error persists, the cause is outside the connection layer — re-triage against the resource-not-found or transient-error playbooks.

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

@@ -2,36 +2,44 @@
 confidence: high
 ---
 
-# GSuite Drive — File or folder not found (HTTP 404)
+# GSuite — Resource not found / item does not resolve (HTTP 404)
 
 ## Context
 
-What this looks like — any of the following messages, all originating from a Google API `HTTP 404 NotFound` response:
+What this looks like — any of the following messages, all meaning the target the activity tried to address does not resolve:
 
 - `File not found: <id>. [404]`
 - `The service drive has thrown an exception. HttpStatusCode is NotFound. File not found`
 - `The service sheets has thrown an exception. HttpStatusCode is NotFound. Requested entity was not found.`
-- `The resource was not found.`
+- `The service gmail has thrown an exception. HttpStatusCode is NotFound. ...` (Gmail message by ID)
+- `The resource was not found.` — the translated form of any Google `HTTP 404 NotFound` (Drive file/folder, spreadsheet, document, **or Gmail message by ID**).
+- `Cannot find item configured with connection ` `` `<connectionId>` `` `.` — the activity's configured item (spreadsheet/file selected via the connection browser) could not be resolved by ID.
+- ``Cannot find item configured with connection `<connectionId>` at path `<path>`.`` — same, when resolution fell back to a path (`FullPath` / `FullPathHint`) and that path doesn't exist in Drive either.
 
 The job faults synchronously the moment the activity tries to resolve the resource.
 
 What activities can produce this error:
-Most `UiPath.GSuite.Activities` activities that take a Drive file, folder, spreadsheet, or document identifier (ID, URL, path, or browse selection) — for example: `GetFileFolderConnections`, `GetFileFolderInfoConnections`, `DownloadFileConnections`, `MoveFileConnections`, `CopyFileConnections`, `DeleteFileOrFolderConnections`, `RenameFileFolderConnections`, `ShareFileFolderConnections`, `UploadFilesConnections` (when targeting an existing parent folder), and any Sheets/Docs activity that opens a spreadsheet or document by ID.
+Any `UiPath.GSuite.Activities` activity that addresses a resource by identifier:
+- **Drive / Sheets / Docs by ID, URL, or path** — `GetFileFolderConnections`, `GetFileFolderInfoConnections`, legacy `GetFileInfo`, `DownloadFileConnections`, `MoveFileConnections`, `CopyFileConnections`, `DeleteFileOrFolderConnections`, `RenameFileFolderConnections`, `ShareFileFolderConnections`, `UploadFilesConnections` (existing parent), and any Sheets/Docs activity that opens a spreadsheet or document by ID. The `Cannot find item configured with connection ...` form comes from activities whose target was picked through the connection's item browser (typically Sheets/Drive `*Connections`). Legacy `GetFileInfo` surfaces the 404 **raw** (`File not found: <id>. [404]`) and faults the job, rather than swallowing it the way the modern `*Connections` variants can — a faulted job, not a null result, is the expected legacy symptom.
+- **Gmail message by ID** — `GetEmailByIdConnections` ("Get Email By Id") when the configured `EmailId` doesn't exist; trigger fetches (`Gmail.Triggers.NewEmailReceived` / `EmailSent`) when the sampled message was deleted between selection and retrieval.
 
 What can cause it:
-- The configured ID, URL, or path resolves to a Drive resource that no longer exists, has been moved to Trash, has been permanently deleted, or was never accessible to the authenticated account. This is the only cause the error can describe — Google has authoritatively returned `404 NotFound` for the request.
+- The configured ID, URL, or path resolves to a resource that no longer exists, has been moved to Trash, has been permanently deleted, or was never accessible to the authenticated account. Google has authoritatively returned `404 NotFound`.
+- For the `Cannot find item configured with connection ...` forms: the browser-selected item ID is stale (the file/spreadsheet was deleted or moved) and no valid path fallback exists.
+- For Gmail by ID: the message ID is stale (copied from an older run, or the message was deleted/trashed), or it belongs to a different mailbox than the one the connection authenticates.
 
 > **Different cause, similar message — do not apply this playbook:**
+> - **`Permission to the resource was denied.`** / **`Invalid authentication credentials.`** (403 / 401) mean access was *denied*, not that the resource is missing — use [connection-and-auth-failures.md](./connection-and-auth-failures.md). (Note: a resource that exists but was never shared with the account can surface as either 404 or 403, depending on the API — check the status class.)
 > - **`ApplyFileLabelsConnections`** can throw `The resource was not found. Please make sure that the selected label is enabled for "Drive and Docs".` That is a label-configuration issue, not a missing file.
 > - **`The document with the name <name> was not found in the specified folder.`** is a name-based lookup miss (no document with that title in the parent), not a 404 against an ID. Treat as a separate scenario.
-> - **`File does not exist.`** (`FileNotFoundException`) refers to a missing **local filesystem** path (e.g., an upload source path or service-account key file), not a Drive resource.
+> - **`File does not exist: <path>`** (`FileNotFoundException`) refers to a missing **local filesystem** path (e.g., a `SendEmail` attachment, an upload source path, or a service-account key file), not a Drive resource — use [invalid-or-null-input.md](./invalid-or-null-input.md).
 
 ## Resolution
 
 The error is unambiguous; no further investigation is needed. Stop the investigation and ask the user to verify the target resource:
 
-1. **Confirm the file or folder still exists** in Google Drive (it may have been deleted, trashed, or moved out of the visible scope).
-2. **Confirm the configured identifier is correct** — the ID, URL, or path on the activity must point to the intended resource. Common mistakes: a stale ID copied from an older version of the file, a URL pointing to a different account's resource, a path that no longer matches the actual folder structure.
-3. **Confirm the connection's authenticated account has access** to the resource. A file owned by another user that was never shared with this account will also surface as `404 NotFound`.
+1. **Confirm the resource still exists** under the connection's account — the Drive file/folder, spreadsheet, or document in Google Drive, or the Gmail message in the mailbox (it may have been deleted, trashed, or moved out of the visible scope).
+2. **Confirm the configured identifier is correct** — the ID, URL, path, or Gmail `EmailId` on the activity must point to the intended resource. Common mistakes: a stale ID copied from an older run, a URL or message ID pointing to a different account's resource, a path that no longer matches the actual folder structure. For the `Cannot find item configured with connection ...` forms, re-select the item through the connection browser so a fresh ID is captured.
+3. **Confirm the connection's authenticated account has access** to the resource. A resource owned by another user that was never shared with this account can also surface as `404 NotFound`.
 
-If the user confirms the resource exists, is reachable in the Drive UI under the same account, and the identifier is correct, the cause is outside the activity — escalate (connection scope, domain policy, sharing) rather than continue under this playbook.
+If the user confirms the resource exists, is reachable in the Google UI under the same account, and the identifier is correct, the cause is outside the activity — escalate (connection scope, domain policy, sharing — see [connection-and-auth-failures.md](./connection-and-auth-failures.md)) rather than continue under this playbook.

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/get-newest-email-not-found.md

@@ -2,17 +2,18 @@
 confidence: high
 ---
 
-# GSuite Get Newest Email — no email matched the filter
+# GSuite Gmail — no email matched the filter (Get Newest Email or trigger debug run)
 
 ## Context
 
-What this looks like:
-- Activity `Get Newest Email` (UiPath.GSuite.Activities, GetNewestEmailConnections) throws `GmailException`
-- Error message: `No email matching the search criteria has been found`
-- Job faults synchronously the moment the activity runs — no retry, no wait
+What this looks like — a `GmailException` with one of these messages:
+- `No email matching the search criteria has been found` — **Get Newest Email** (`GetNewestEmailConnections`). Faults synchronously the moment the activity runs — no retry, no wait.
+- `No email matching the filter criteria, received in the last 1 hour has been found. Please generate a new email that fits the criteria and run the workflow again` — **New Email Received** trigger (`Gmail.Triggers.NewEmailReceived`) executed in **debug / test mode**.
+- `No email matching the filter criteria, sent in the last 1 hour has been found. Please generate a new email that fits the criteria and run the workflow again` — **Email Sent** trigger (`Gmail.Triggers.EmailSent`) executed in **debug / test mode**.
 
 What can cause it:
-- The Gmail mailbox contains zero messages matching the configured filter at the moment the activity executes. This is the only cause — the activity issues a single Gmail API query with `MaxResults = 1` and throws when the result is empty.
+- The Gmail mailbox contains zero messages matching the configured filter at the moment the activity executes. For `GetNewestEmailConnections`, the activity issues a single Gmail API query with `MaxResults = 1` and throws when the result is empty.
+- For the **triggers**: this only occurs in debug/test mode, where the trigger fetches a *sample* event by querying the mailbox for a matching message **received/sent in the last 1 hour**. At production runtime the trigger is driven by an Orchestrator event id and waits for real events instead of throwing — so this message means a test run found no qualifying recent email, not that the production trigger is broken.
 
 What to look for:
 - The exact filter the activity was configured with: `Folder`, `FilterSelectionMode` (ConditionBuilder vs Query), `QueryFilter` (raw Gmail query), or the structured `Filter` collection (`From`, `To`, `Subject`, `Body`, `DateAndTime`, `Cc`, `Bcc`, `Categories`, `Filename`, `Labels`)
@@ -22,11 +23,11 @@ What to look for:
 ## Investigation
 
 1. From the job logs or workflow, capture the exact values of every filter property listed above and the job start timestamp.
-2. Confirm the activity is `GetNewestEmailConnections` (display name "Get Newest Email") and not a long-running trigger — this activity does not poll or wait.
+2. Identify which activity threw: `GetNewestEmailConnections` (one-shot query, message text `No email matching the search criteria has been found`) or a trigger run in debug/test mode (message text mentions `received/sent in the last 1 hour`). For a trigger, also confirm this was a test/debug execution, not production — at production runtime the trigger waits for events and does not throw this.
 3. There is nothing further to verify programmatically; the Gmail API has already authoritatively returned zero matches for that query. Proceed to Resolution.
 
 ## Resolution
 
 - **In all cases:** Report the captured filter values and job timestamp to the user and ask them to sign in to the target Gmail mailbox and confirm whether any message matching those filters was present at or before the job run time. Then:
-  - **If no matching email existed:** This is expected behavior, not a defect. Recommend either (a) loosening the filter (remove `UnreadOnly`/`WithAttachmentsOnly`/`ImportantOnly`/`StarredOnly`, broaden `Subject`/`From`/`DateAndTime`, switch `FilterSelectionMode` to a less restrictive `QueryFilter`), or (b) wrapping the activity in a Try/Catch so the workflow handles the empty-mailbox case explicitly, or (c) scheduling the job to run after the expected email arrives.
+  - **If no matching email existed:** This is expected behavior, not a defect. Recommend either (a) loosening the filter (remove `UnreadOnly`/`WithAttachmentsOnly`/`ImportantOnly`/`StarredOnly`, broaden `Subject`/`From`/`DateAndTime`, switch `FilterSelectionMode` to a less restrictive `QueryFilter`), or (b) wrapping the activity in a Try/Catch so the workflow handles the empty-mailbox case explicitly, or (c) scheduling the job to run after the expected email arrives. **For a trigger debug run:** send/receive an email matching the filter within the last hour, then re-run the test — the message says as much (`generate a new email that fits the criteria and run the workflow again`).
   - **If a matching email did exist in the mailbox at that time:** Ask the user to copy the matching message's raw Gmail search query (e.g., `from:foo@bar.com subject:"X" has:attachment`) and compare it against the activity's configured filter to identify the mismatch (common culprits: label scoping, `Folder` set to a label that excludes Inbox, time-zone offset on `DateAndTime`, case-sensitivity expectations that Gmail does not honor).

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/invalid-or-null-input.md

@@ -0,0 +1,68 @@
+---
+confidence: medium
+---
+
+# GSuite — Invalid or null activity input (client-side validation)
+
+## Context
+
+This playbook covers errors thrown **inside the activity, before any Google API call is made**, because an input property is null, empty, out of range, or otherwise invalid. The root cause is always in the workflow itself — a variable that wasn't populated, an upstream activity that returned nothing, a hard-coded address that's wrong, or a property combination the activity rejects. The connection and the Google resource are irrelevant; do not investigate them.
+
+What this looks like — any of the following messages:
+
+- `Value cannot be null. (Parameter '<name>')` — a required input (`<name>` names it, e.g. `EmailId`, `range`, `spreadsheetId`, `SheetName`, `DataRow`) was null at runtime. (`Value cannot be null` with no parameter is the same error without a captured name.)
+- `The object used in the activity does not exist.` — a `NullReferenceException` was mapped to this message: a `DataTable`, email object, range handle, or other object the activity dereferences was null. Commonly the output of a previous activity (a search that found nothing, a read that returned null) fed straight into this one.
+- `Column not found: <name>` — a row/column operation referenced a column by name that doesn't exist in the range (header typo, or the read range didn't include that column).
+- `Column index <i> is outside of the selected range <range>` — a column index is beyond the bounds of the range being iterated.
+- `RelativeRowIndex <i> outside the range: 0 to <n>.` — `Write Row` (WriteMode = Overwrite) targeted a row position past the end of the range (range has rows `0..n`, position `<i>` exceeds it).
+- `RelativeColumnIndex <i> outside the range: 0 to <n>.` — same, for column width: the data is wider than the overwrite range allows.
+- `Named ranges with cell value are invalid. Named ranges require no cell input.` — `Write Cell` was given **both** a named range *and* a `Cell` value; a named range already defines the target, so `Cell` must be empty.
+- `The provided data table does not have any columns.` — an empty `DataTable` (zero columns) was passed to a write activity.
+- `<property> must be a positive number` — a count property (e.g. `MaxResults` on legacy `GetMailMessages`) was set to 0 or negative.
+- `You do not have the following labels` — a Gmail activity referenced one or more label names that don't exist in the account (followed by the offending label names).
+- `Cannot iterate over the QuickHandle item.` — the result of a `For Each Row` was used in an operation that needs a valid current-row handle but received an incompatible object.
+- `The selected folder does not exist.` — legacy local-OAuth datastore: the configured credential-storage `Folder` path is missing on the robot machine.
+- `File does not exist: <path>` — a `System.IO.FileNotFoundException`: a configured **local** file path does not exist on the robot machine. Legacy `SendEmail` attachment path (validated as the activity assembles attachments, before any Gmail send), an upload source path, or a service-account key path. This is a local-filesystem miss, **not** a Drive 404.
+- `Could not extract an object Id from the Url '<url>'.` — an `ArgumentOutOfRangeException`: a Drive activity that resolves a file/folder by ID *or* URL (legacy `GetFileInfo` and any `CloudObjectIdentifier`-based by-ID/URL activity) was given a URL string with no extractable ID segment. Malformed/truncated link, not a missing resource.
+- `You must provide a value for at least one of the following properties: To, Cc, Bcc` — legacy `SendEmail` (non-draft) with `To`, `Cc`, and `Bcc` all empty. Validated at design time; satisfied by populating a recipient or setting `IsDraft = True`.
+
+The job faults synchronously the instant the activity validates the input; there is no API round-trip, no retry.
+
+What activities can produce these errors:
+Any activity with the relevant input. Null/`Value cannot be null` and `The object used in the activity does not exist.` are universal (every activity has required inputs). The range/row/column messages come from Sheets activities (`WriteRangeConnections`, `WriteCellConnections`, `WriteRowConnections`, `WriteColumnConnections`, `ReadRange(Connections)`, `ForEachRowConnections`, and their legacy equivalents). `<property> must be a positive number` and `You do not have the following labels` come from Gmail retrieval activities such as legacy `GetMailMessages`. `File does not exist: <path>` and the recipient-required message come from legacy `SendEmail` (missing attachment path / all recipients empty); `Could not extract an object Id from the Url ...` comes from legacy `GetFileInfo` and other Drive by-ID/URL activities given a malformed URL.
+
+What can cause it:
+- A workflow variable bound to the property was never assigned, or an expression evaluated to null/empty at runtime.
+- The output of an upstream activity (a search with no match, a read that returned an empty result) was passed directly in without a null check.
+- A hard-coded address is wrong: an out-of-bounds row/column position, a misspelled column name, a named range combined with a cell value.
+- An empty or zero-column `DataTable` was built and passed to a write.
+- A configuration value (`MaxResults`, a label name, a local datastore folder) is invalid for the environment.
+- A configured local file path (a `SendEmail` attachment, an upload source) doesn't exist on the robot, or a Drive `FileId` is a malformed URL with no extractable ID.
+- A non-draft `SendEmail` has no recipient in any of `To`/`Cc`/`Bcc`.
+
+> **Different cause — do not apply this playbook:**
+> - **`Invalid data[0]: Unable to parse range: <Sheet>!<Cell>`** is a **server-side** Google 400 (the range reached Google and Google rejected its A1 syntax) — use [sheets-invalid-range.md](./sheets-invalid-range.md). The errors in *this* playbook are thrown before the call leaves the robot.
+> - **`This action would increase the number of cells ...`** → [sheets-cell-limit-exceeded.md](./sheets-cell-limit-exceeded.md).
+> - **`The resource was not found.`** / **`Cannot find item configured with connection ...`** (a target that doesn't resolve) → [drive-file-not-found.md](./drive-file-not-found.md).
+> - 401/403/auth-timeout → [connection-and-auth-failures.md](./connection-and-auth-failures.md).
+
+## Investigation
+
+1. **Read the parameter name or value out of the message** — it names the offending input directly (`Parameter '<name>'`, the index in `outside the range`, the column in `Column not found`).
+2. **Trace that input back to its source in the workflow** — is it a literal, a variable, or the output of a previous activity? Capture how it's assigned.
+3. **If the input comes from an upstream activity,** check whether that activity could legitimately have returned null/empty (e.g. a search with no results) — that's the real fault to handle.
+4. **For range/row/column bounds,** compare the configured index/position/width against the actual dimensions of the target range.
+
+## Resolution
+
+- **If a required input was null (`Value cannot be null` / `The object used in the activity does not exist.`):** Ensure the property is assigned before the activity runs. If it comes from an upstream activity that can return nothing, add a null/empty guard (If, or Try/Catch) and handle the empty case explicitly rather than feeding it forward.
+- **If a row/column position or width is out of range (`RelativeRowIndex` / `RelativeColumnIndex` / `Column index ... outside`):** Correct the position/index to fall within the target range, or size the write data to the range. For `Write Row` Overwrite, the position must be `0..(range rows − 1)`.
+- **If a column name is wrong (`Column not found`):** Fix the column name to match the read range's header, or widen the read range to include it.
+- **If a named range was combined with a cell (`Named ranges with cell value are invalid`):** Clear the `Cell` input when using a named range.
+- **If an empty DataTable was passed (`does not have any columns`):** Build the DataTable with its columns defined before writing.
+- **If a count is non-positive (`must be a positive number`):** Set `MaxResults` (or the named property) to a value ≥ 1.
+- **If labels don't exist (`You do not have the following labels`):** Correct the label names to match labels that exist in the Gmail account (labels are case-sensitive and user-defined).
+- **If the local datastore folder is missing (`The selected folder does not exist.`):** Create the configured credential-storage folder on the robot machine or point the legacy scope at an existing path.
+- **If a local file is missing (`File does not exist: <path>`):** Stage the file at the configured path on the robot, or correct the path (the attachment / upload-source entry). For unattended runs avoid machine-local / user-profile paths.
+- **If a Drive URL won't parse (`Could not extract an object Id from the Url ...`):** Supply a valid file ID or a well-formed Drive URL containing the ID segment.
+- **If `SendEmail` has no recipient:** Populate `To`, `Cc`, or `Bcc`, or set `IsDraft = True` to save a draft without recipients.

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/transient-and-timeout-errors.md

@@ -0,0 +1,52 @@
+---
+confidence: medium
+---
+
+# GSuite — Transient service errors, rate limits, and per-request timeouts
+
+## Context
+
+This playbook covers failures where the request reached (or tried to reach) Google and failed for a reason that is environmental and often temporary: a Google-side 5xx, a rate/quota-per-interval limit, a network fault, or a per-request timeout. The activity inputs and the target resource are usually fine — the same workflow often succeeds on retry. Distinguish **intermittent** (transient, retry) from **consistent** (network path or a timeout set too low).
+
+What this looks like — any of the following messages:
+
+- `Internal server error occurred. Please try again later.` — wrapped `GSuiteException`, Google **HTTP 500**. Transient.
+- `The service is currently unavailable. Please try again later.` — wrapped `GSuiteException`, Google **HTTP 503**. Transient (Google maintenance / overload).
+- `Network error occurred before reaching the server. Typically a network outage or misconfiguration.` — wrapped `GSuiteException`, **HTTP 502**.
+- `Request deadline exceeded.` — wrapped `GSuiteException`, **HTTP 504**.
+- `The current state conflicts with what the request expects.` — wrapped `GSuiteException`, **HTTP 409**.
+- `The daily limit was exceeded.` / `The user rate limit was exceeded.` / `The rate limit was exceeded.` — wrapped `GSuiteException`, Google **HTTP 429** with reason `dailyLimitExceeded` / `userRateLimitExceeded` / `rateLimitExceeded`. The connection is making more requests than Google's per-day or per-interval quota allows.
+- `An error occurred in the activity.` — the **generic fallback**: a Google API error whose status code and reason matched none of the known mappings (for example, a 429 without a recognized reason, or an uncommon status). The real status is in the inner exception / activity trace — read it before concluding; do not assume a specific cause from this text alone.
+- A raw `System.Net.Http.HttpRequestException` — a network-layer failure (DNS resolution, connection reset, TLS handshake, firewall/proxy drop). Legacy activities surface this raw; modern activities may wrap it.
+- `A task was canceled.` (a `System.Net.Http.TaskCanceledException` / `OperationCanceledException`) — the Google API request exceeded the activity's **per-request** `RequestTimeout` (the `HttpClient` timeout). **This is not a `System.TimeoutException`** — a `TimeoutException` in GSuite only ever comes from the *authentication* phase (see the connection-and-auth playbook). A per-request timeout cancels the task instead.
+
+**Trigger activities** (`Gmail.Triggers.NewEmailReceived`, `Gmail.Triggers.EmailSent`, etc.) wrap their work in a retry-with-backoff: they automatically retry socket-level `HttpRequestException` and 5xx `GoogleApiException` (exponential backoff capped at 30s) before surfacing. So a transient error that faults a trigger generally means the condition persisted across the entire retry window, not a single blip.
+
+What can cause it:
+- **Transient Google fault** (5xx): Google service degradation, regional outage, or maintenance. Self-resolves.
+- **Rate / quota limit** (429): the connection (or the whole project) exceeded Google's per-minute or per-day API quota — often a burst of requests in a loop, or many robots sharing one connection.
+- **Network path failure** (`HttpRequestException`): DNS, proxy, firewall, or connectivity loss between the robot and Google.
+- **Per-request timeout** (`A task was canceled.`): the call genuinely took longer than `RequestTimeout` (large payload, slow network), or `RequestTimeout` is set too low for the operation.
+
+> **Different cause — do not apply this playbook:**
+> - **`Authentication attempt took longer than <N> seconds ...`** is an *auth-phase* `TimeoutException`, a connection problem — use [connection-and-auth-failures.md](./connection-and-auth-failures.md).
+> - **`The storage quota was exceeded.`** / **`Upload failed after <N> bytes ...`** is a *storage* quota (403), not an API rate limit — use [upload-storage-quota-exceeded.md](./upload-storage-quota-exceeded.md).
+> - A clean 401/403/404 with a definite message → connection-and-auth or drive-file-not-found, not this playbook.
+
+## Investigation
+
+1. **Read the embedded status code / inner exception, not just the sentence.** A wrapped `GSuiteException` carries the original status; for `An error occurred in the activity.` the activity trace holds the real Google status and reason. Classify: 5xx (transient), 429 (rate limit), network (`HttpRequestException`), or timeout (`A task was canceled.`).
+2. **Determine intermittent vs. consistent.** Check whether the same activity/connection succeeded on adjacent runs or fails every time. Intermittent points to a transient 5xx or a momentary network blip; consistent points to a network-path problem, an exhausted quota, or a `RequestTimeout` that is too low.
+3. **For 429:** check the request volume around the failure — a loop firing many calls, or many jobs sharing one connection — and whether it's a daily vs per-minute limit (the message distinguishes them).
+4. **For `A task was canceled.`:** capture the configured `RequestTimeout` and the expected size/latency of the operation.
+5. **For network errors / persistent 5xx:** check the Google Workspace Status Dashboard for an active incident, and verify the robot's outbound connectivity (proxy, firewall, DNS) to Google endpoints.
+
+## Resolution
+
+- **If transient (intermittent 5xx / momentary network):** This is expected and recoverable. Wrap the activity in a Retry Scope (or rely on the trigger's built-in retry) and rerun. No configuration change needed if it succeeds on retry.
+- **If rate-limited (429):** Reduce request rate — add delays or batching in loops, spread load across connections, or request a higher Google API quota. A `dailyLimitExceeded` resets at the start of the next day (Pacific time); per-user/per-minute limits clear within the minute.
+- **If a persistent network failure (`HttpRequestException`):** Fix the network path — confirm the robot can reach Google API endpoints through the configured proxy/firewall, and that DNS resolves. Not a workflow defect.
+- **If a per-request timeout (`A task was canceled.`):** Raise the activity's `RequestTimeout` if the operation is legitimately slow (large read/write), or reduce the payload size. Confirm network latency to Google is normal.
+- **If `An error occurred in the activity.` and the inner status doesn't fit any of the above:** report the captured inner status/reason from the trace and re-triage — the generic message means the specific cause was not one of the mapped patterns.
+
+If a 5xx or network error persists well beyond a normal retry window and the Google Status Dashboard shows no incident, escalate with the captured traces (endpoint, status, timing) rather than continuing to retry.

package/skills/uipath-troubleshoot/references/activity-packages/gsuite-activities/playbooks/upload-storage-quota-exceeded.md

@@ -19,7 +19,7 @@ What this looks like — `GSuiteException` with the format `Upload failed after
 
 What activities can produce this error:
 - **Drive uploads** — `UploadFilesConnections` (modern), legacy `UploadFile`
-- **Gmail attachment uploads** — `SendEmailConnections`, `ReplyToEmailConnections`, `ForwardEmailConnections` when the email carries an attachment large enough to require a multipart upload
+- **Gmail attachment uploads** — `SendEmailConnections`, `ReplyToEmailConnections`, `ForwardEmailConnections`, legacy `SendEmail` when the email carries an attachment large enough to require a multipart upload
 
 What can cause it — two underlying quota conditions, both surfaced as Google 403:
 - **`storageQuotaExceeded`** — the authenticated user's Drive storage is full. Applies to the entire account quota (free tier, Workspace plan storage, or pooled storage).

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

@@ -4,10 +4,13 @@
 
 | Issue | Confidence | Description | Playbook |
 |-------|:---:|-------------|----------|
-| Get Newest Email — No Matching Email Found | High | Gmail mailbox contains zero messages matching the configured filter at the moment the activity runs (`GmailException: No email matching the search criteria has been found`) | [get-newest-email-not-found.md](./playbooks/get-newest-email-not-found.md) |
+| Gmail — No Matching Email Found (Get Newest Email or trigger debug run) | High | Gmail mailbox contains zero messages matching the configured filter when the activity runs — `Get Newest Email` (`No email matching the search criteria has been found`) or a `NewEmailReceived`/`EmailSent` trigger in debug mode (`No email matching the filter criteria, received/sent in the last 1 hour has been found...`) | [get-newest-email-not-found.md](./playbooks/get-newest-email-not-found.md) |
 | Drive — Name Conflict in Specified Folder | High | Drive activity (CreateFolder, CopyFile, MoveFile, Rename, Upload, CreateSpreadsheet, CreateDocument) throws `GSuiteException: Multiple items with the name <name> found in the specified folder.` because the configured `ConflictResolution` cannot resolve a duplicate name | [drive-multiple-items-name-conflict.md](./playbooks/drive-multiple-items-name-conflict.md) |
 | Add Sheet — Sheet Name Already Exists | High | Target spreadsheet already contains a sheet (tab) with the configured `SheetName` (case-insensitive) and `ConflictResolution = Fail` (`GSuiteException: A sheet with the same name already exists.`) | [add-sheet-name-conflict.md](./playbooks/add-sheet-name-conflict.md) |
-| Drive — File or Folder Not Found (404) | High | Drive activity fails to resolve the configured ID/URL/path because the resource was deleted, trashed, or is not accessible to the connection (`File not found: <id>. [404]` / `HttpStatusCode is NotFound` / `The resource was not found.`) | [drive-file-not-found.md](./playbooks/drive-file-not-found.md) |
+| Resource Not Found / Item Does Not Resolve (404) | High | Activity fails to resolve the configured target because the resource was deleted, trashed, or is not accessible to the connection — a Drive file/folder/spreadsheet/document, a Gmail message by ID (`GetEmailByIdConnections`), or a browser-selected item (`File not found: <id>. [404]` / `HttpStatusCode is NotFound` / `The resource was not found.` / ``Cannot find item configured with connection `<id>` [at path `<path>`].``) | [drive-file-not-found.md](./playbooks/drive-file-not-found.md) |
+| Connection, Authentication, and Permission Failures | Medium | Failure in the identity/connection layers, not the resource: auth timeout (`Authentication attempt took longer than <N> seconds...`), expired/invalid token (`Invalid authentication credentials.` / `Authentication error...`), authorization denied (`Permission to the resource was denied.` / `The user does not have sufficient permissions for the file.` / `domainPolicy`), or a raw `ConnectionHttpException` (incl. design-time browse `CNS1044`/`CNS1045`) | [connection-and-auth-failures.md](./playbooks/connection-and-auth-failures.md) |
+| Invalid or Null Activity Input (client-side) | Medium | Activity throws before any API call because an input is null, empty, out of range, or an invalid property combination (`Value cannot be null. (Parameter '<x>')` / `The object used in the activity does not exist.` / `Column not found: <name>` / `RelativeRowIndex/RelativeColumnIndex <i> outside the range...` / `Named ranges with cell value are invalid...` / `<property> must be a positive number` / `You do not have the following labels`) | [invalid-or-null-input.md](./playbooks/invalid-or-null-input.md) |
+| Transient Service Errors, Rate Limits, and Per-Request Timeouts | Medium | Environmental/temporary failure reaching Google: 5xx (`Internal server error...` / `The service is currently unavailable...`), rate limit/429 (`The daily/user rate limit was exceeded.`), network (`HttpRequestException`), per-request `RequestTimeout` (`A task was canceled.` — not a `TimeoutException`), or the generic fallback `An error occurred in the activity.` | [transient-and-timeout-errors.md](./playbooks/transient-and-timeout-errors.md) |
 | Upload — Drive Storage Quota or Shared Drive File Limit Exceeded | High | Upload activity (Drive `UploadFilesConnections`, legacy `UploadFile`, or Gmail send/reply/forward with attachments) fails because the user's Drive storage is full (`storageQuotaExceeded`) or the destination shared drive has hit the 500K item limit (`Upload failed after <N> bytes. ...`) | [upload-storage-quota-exceeded.md](./playbooks/upload-storage-quota-exceeded.md) |
 | Sheets — 10 Million Cell Limit Exceeded | High | Sheets write/expand activity (Write Range/Cell/Row/Column, AutoFill, CopyPaste, Add Sheet, plus legacy AppendRow, CopySheet, BatchUpdateValuesScope, Add modes of AddDelete*) fails because the operation would push the spreadsheet past Google's 10M cell cap (`HttpStatusCode is BadRequest. This action would increase the number of cells in the workbook above the limit of 10000000 cells.`) | [sheets-cell-limit-exceeded.md](./playbooks/sheets-cell-limit-exceeded.md) |
 | Sheets — Invalid Range / Unable to Parse Range | Medium | Sheets read/write activity passes a malformed A1-notation range to the Sheets API (`HttpStatusCode is BadRequest. Invalid data[0]: Unable to parse range: <SheetName>!<CellRef>`). Common causes: 1-indexing mistake (row 0), empty/null range, unquoted sheet names with spaces, stale sheet references, off-by-one in dynamic construction | [sheets-invalid-range.md](./playbooks/sheets-invalid-range.md) |

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

@@ -0,0 +1,28 @@
+# Mail Activities (classic)
+
+Activities from the classic mail packages that talk to a mail system directly from the Robot — distinct from the modern Graph/OAuth activities in **o365-activities** (`UiPath.MicrosoftOffice365.Activities`) and the Gmail activities in **gsuite-activities**. The classic mail packages are:
+
+- **Outlook (desktop COM)** — `UiPath.Mail.Outlook.Activities`. Drives the locally installed **Outlook desktop application** through COM interop: `Send Outlook Mail Message` (`SendOutlookMail`), `Get Outlook Mail Messages` (`GetOutlookMailMessages`), `Move Outlook Mail Message`, `Reply To Outlook Mail Message`, `Mark Outlook As Read`. Requires Outlook installed **and** a configured mail profile in the session the Robot runs as.
+- **SMTP / IMAP / POP3 / Exchange** — `UiPath.Mail.SMTP.Activities` (`Send SMTP Mail Message`), `UiPath.Mail.IMAP.Activities`, `UiPath.Mail.POP3.Activities`, `UiPath.Mail.EWS.Activities`. Protocol-level mail that talks to a mail server directly, with no desktop client dependency.
+
+## How Outlook (desktop COM) activities run
+
+`Send Outlook Mail Message` does **not** call a mail API. It:
+
+1. Attaches to (or launches) the local **OUTLOOK.EXE** via COM interop, under the Windows user the Robot runs as.
+2. Uses that user's default (or a named) **Outlook profile / account** to compose and send the message through the Outlook Object Model.
+3. Returns when Outlook accepts the item into the Outbox / Sent Items.
+
+Because the call goes through the desktop application, failures cluster around the **COM layer** (Outlook installed/registered, process bitness, orphaned `OUTLOOK.EXE`), the **session/UI** (a security prompt or Work Offline state blocking the call), and the **inputs** (uninitialized `To`/`Subject`/`Body` or a bad attachment path). This makes the Outlook COM activities fragile on unattended Robots, where there is no interactive desktop to dismiss a prompt.
+
+> For unattended or server-side mail with no Outlook install, prefer **Send SMTP Mail Message** (`UiPath.Mail.SMTP.Activities`) or the modern Graph **o365-activities** — both avoid the desktop COM dependency entirely.
+
+## Common Failure Families
+
+- **COM cast / library not registered** — `Unable to cast COM object …` / `Library not registered` (`REGDB_E_CLASSNOTREG`, `TYPE_E_LIBNOTREGISTERED`). Outlook not installed/registered, a process-vs-Outlook **bitness** mismatch, corrupted Office registry/type-library, or an orphaned `OUTLOOK.EXE` from a prior run.
+- **Timeout / hang** — the activity blocks until `TimeoutMS` elapses. A hidden security prompt ("A program is trying to send an email message on your behalf"), Outlook in **Work Offline** mode, or a slow first-launch of the profile.
+- **Uninitialized input** — `Object reference not set to an instance of an object` from a null `To`/`Subject`/`Body` variable or an empty/null attachment path.
+
+## Package
+
+NuGet: `UiPath.Mail.Outlook.Activities` (desktop COM), `UiPath.Mail.SMTP.Activities` (SMTP), `UiPath.Mail.IMAP.Activities` / `UiPath.Mail.POP3.Activities` / `UiPath.Mail.EWS.Activities` (protocol). The Outlook COM activities require Outlook installed and a profile on the Robot host; protocol activities require only network access to the mail server.

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

@@ -0,0 +1,105 @@
+---
+confidence: medium
+---
+
+# Delete Outlook Mail Message Failures
+
+## Context
+
+A `UiPath.Mail.Outlook.Activities` `Delete Outlook Mail Message` (`DeleteOutlookMailMessage`) activity deletes a `MailMessage` from the **locally installed Outlook desktop application** through COM interop. It takes a `MailMessage` (typically an item from a preceding `Get Outlook Mail Messages`) plus an optional `Account`, and removes that item under the Outlook profile of the Windows user the Robot runs as. Failures cluster around a **stale message reference** (the item moved/deleted between fetch and delete), **mutating the message collection inside a loop**, the **New Outlook** client removing the desktop COM API, the **COM session being blocked** (modal dialog / privilege mismatch), and **mailbox permissions** (the Robot account lacking delete rights, especially on shared mailboxes).
+
+Delete shares the desktop-COM surface with the other Outlook activities — the New-Outlook and COM-blocked/privilege failures are diagnosed like [move-outlook-mail-failures.md](./move-outlook-mail-failures.md) branch 4 and [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 2, and `Account`/shared-mailbox handling matches [get-outlook-mail-failures.md](./get-outlook-mail-failures.md) branch 1. What is distinctive to Delete is the **stale-reference** fault and the **collection-modified-in-loop** error. For unattended / server-side deletes with no desktop Outlook, prefer the modern Graph **o365-activities**.
+
+What this looks like — Delete Outlook Mail Message faults surface as one of these signatures:
+
+- `The operation failed. An object could not be found.` — the target message no longer exists at that location — branch 1.
+- `Collection was modified; enumeration operation may not execute.` raised inside a `For Each` over the message list — branch 2.
+- The automation **broke completely after a system/Office update** that flipped the host to **New Outlook** — branch 3.
+- `The operation has timed out` / an intermittent **freeze** with no clean exception — branch 4.
+- A **permission / access-denied** error (or a folder that resolves but cannot be modified), commonly on a **shared mailbox** — branch 5.
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Stale message reference.** The `MailMessage` passed to Delete no longer exists in that exact location: a human user, another automation, or an Outlook rule moved or deleted the item **after** `Get Outlook Mail Messages` retrieved it. Surfaces as `The operation failed. An object could not be found.` Hallmark: large time gap (or concurrent processing) between fetch and delete.
+2. **Collection modified inside the loop.** A `For Each` iterates the `List<MailMessage>` from Get, and Delete runs **directly inside** that loop. Deleting an item mutates the live collection mid-enumeration, invalidating the loop pointer — `Collection was modified; enumeration operation may not execute.`
+3. **New Outlook (desktop COM API removed).** The host updated to Microsoft's **New Outlook** (web-hybrid client), which removes the Outlook Desktop COM API the classic activities rely on. The activity can no longer bind to an Outlook COM server. Hallmark: worked, then broke completely right after an update.
+4. **COM session blocked (modal dialog / privilege).** The local Outlook COM interop is blocked: a **modal dialog** is foregrounded (notably the programmatic-access / "a program is trying to access email" warning), or UiPath and Outlook run at **mismatched privilege levels** (one elevated/Administrator, the other standard), so Windows blocks the cross-process call. Surfaces as a timeout or a hang.
+5. **Mailbox permission / access denied.** The Robot account lacks the read/write/**delete** rights on the target folder — most common on a **shared mailbox** where the account has Send-As but not Full Access, and/or the shared mailbox address is not set in `Account`.
+
+What to look for:
+
+- **The exception text and the fetch→delete gap.** `An object could not be found` with a delay/concurrency between Get and Delete → branch 1; `Collection was modified` inside a loop → branch 2; "broke after an update" → branch 3; a timeout/freeze → branch 4; an access/permission error → branch 5.
+- **The workflow structure** — whether Delete sits **inside a `For Each`** over the Get output (branch 2), and how long/much runs between Get and Delete (branch 1). From `Main.xaml`.
+- **Outlook client variant + session/privilege** — Classic vs New Outlook (branch 3), and whether a modal dialog or a UiPath-vs-Outlook elevation mismatch could block COM (branch 4). Host-verifiable.
+- **`Account` + mailbox rights** — whether the target is a shared mailbox, whether its address is in `Account`, and whether the Robot account has **Full Access** (not just Send-As). Load-bearing for branch 5.
+
+## Investigation
+
+Go in this order — cheaper checks first.
+
+1. **Capture the exact error, the workflow structure, and the host.** From `uip or jobs get <job-key> --output json` → `Info`: the exception class and message. From workflow source (`.xaml`): whether `Delete Outlook Mail Message` runs inside a `For Each` over the Get output, the gap between Get and Delete, and the `Account`. From the job: the Robot **host**, attended vs unattended, and the Outlook client variant if known.
+
+2. **Branch the diagnostic on the signature.**
+   - `The operation failed. An object could not be found.` → branch 1; go to step 3.
+   - `Collection was modified; enumeration operation may not execute.` → branch 2; go to step 4.
+   - "Broke completely after an update" / New Outlook on the host → branch 3; go to step 5.
+   - Timeout / freeze, no clean exception → branch 4; go to step 6.
+   - Permission / access-denied error → branch 5; go to step 7.
+
+3. **Confirm branch 1 (stale reference).** Confirm the failing item is one Delete tried to remove and that something could have moved/deleted it between fetch and delete — a long delay, a parallel job, a user, or an Outlook rule on the same folder. An `object could not be found` with that gap confirms the branch.
+4. **Confirm branch 2 (collection modified in loop).** In the source, confirm Delete (or a Move/modify) runs **inside** a `For Each` iterating the live `MailMessage` collection from Get. The `Collection was modified` error from inside the loop confirms the branch — it is a workflow-structure bug, not an Outlook problem.
+5. **Confirm branch 3 (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 confirms the branch. (Same surface as [move-outlook-mail-failures.md](./move-outlook-mail-failures.md) branch 4.)
+6. **Confirm branch 4 (COM blocked / privilege).** Check whether a modal dialog (programmatic-access warning) could be foregrounded and whether UiPath and Outlook run at the **same privilege level**. A timeout/freeze on an unattended host, or an elevation mismatch, confirms the branch. (Same surface as [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 2 / [get-outlook-mail-failures.md](./get-outlook-mail-failures.md) branch 3.)
+7. **Confirm branch 5 (permission / access).** Check whether the target is a **shared mailbox**, whether its address is set in `Account`, and whether the Robot account has **Full Access** (not just Send-As). A delete-denied / access error on a shared folder confirms the branch.
+
+The root cause must name **which of the five surfaces** the failure maps to, with the specific evidence: the exception text, the fetch→delete gap, whether Delete is inside a loop, the Outlook client/session/privilege state, and the `Account` + mailbox rights. A generic "delete failed" is not a confirmed finding.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Stale message reference:**
+  - Minimize the time and work between `Get Outlook Mail Messages` and the delete so the item cannot move out from under you; fetch immediately before deleting.
+  - Wrap the delete in a `Try Catch` that tolerates an already-moved/already-deleted item (the work is effectively done) rather than faulting the job.
+  - If another job/user/rule legitimately competes for the same folder, re-fetch and re-confirm the item before deleting.
+
+- **Branch 2 — Collection modified inside the loop:**
+  - Do **not** delete (or otherwise mutate the collection) directly inside a `For Each` over the live `MailMessage` list. Either:
+    - iterate over a **copy** — `mailMessages.ToList()` — so deletes do not disturb the enumerator, or
+    - loop **backwards by index** so removing an item does not shift the positions still to visit, or
+    - inside the loop use **Move Outlook Mail Message** to shift targeted items to `Deleted Items` (or a temp subfolder) and delete them in a second pass after the loop.
+
+- **Branch 3 — New Outlook:**
+  - Revert the host's Outlook to **Classic Outlook** so the desktop COM API the activity needs is present again, or
+  - migrate the workflow to the modern Microsoft 365 / Graph activities ([o365-activities](../../o365-activities/overview.md)), which delete over a web connection rather than local desktop COM. (Same fix as [move-outlook-mail-failures.md](./move-outlook-mail-failures.md) branch 4.)
+
+- **Branch 4 — COM session blocked / privilege:**
+  - Run UiPath (Studio/Robot) and Outlook at the **same privilege level** — ideally both standard user, not Administrator.
+  - Resolve the programmatic-access dialog at its source: `Outlook > File > Options > Trust Center > Trust Center Settings > Programmatic Access`, and confirm antivirus is current and registered with Windows Security Center so the "a program is trying to access email" warning does not fire unattended. (Same surface/fix as [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) branch 2.)
+
+- **Branch 5 — Mailbox permission / access:**
+  - Set the **shared mailbox address explicitly in the `Account`** property of the mail activities.
+  - Have the Exchange administrator grant the Robot's Active Directory account **Full Access** permission (not just Send-As) on the target shared mailbox / folder, so it can read, write, and delete there.
+
+## Anti-patterns (what NOT to do)
+
+- **"Add a Delay before the delete to let things settle."** A delay makes branch 1 *worse* — the longer the gap between fetch and delete, the more likely the item moved. Fetch-then-delete promptly, and handle the already-gone case in a catch.
+- **"Wrap the loop-delete in a Try Catch and keep going."** Swallowing the `Collection was modified` error does not fix branch 2 — the enumeration is already broken and remaining items are skipped. Iterate a copy / backwards, or Move-then-delete.
+- **"Run UiPath as Administrator so it can delete."** Elevation does not grant mailbox delete rights and usually *breaks* COM via a privilege mismatch (branch 4). Match privilege levels; fix mailbox rights via Exchange (branch 5).
+- **"Reinstall Office / downgrade the package after the post-update break."** If the host flipped to New Outlook (branch 3), neither helps — revert to Classic Outlook or move to the Graph activities.
+
+## Prevention (cross-branch)
+
+- Fetch immediately before deleting and guard the delete with a Try Catch for already-moved/deleted items; avoid long gaps and concurrent processing of the same folder (branch 1).
+- Never mutate the live `MailMessage` collection inside its own `For Each` — iterate a `.ToList()` copy or backwards by index, or Move-then-delete in a second pass (branch 2).
+- Pin Robot hosts to **Classic Outlook** (or move deletes to the Graph o365 activities) so a New-Outlook flip cannot break the COM activities (branch 3).
+- Keep UiPath and Outlook at the same privilege level and pre-configure programmatic access / antivirus so no modal dialog blocks unattended runs (branch 4).
+- Provision the Robot account with **Full Access** on every shared mailbox it must delete from, and set `Account` to the shared address at design time (branch 5).
+
+## Related
+
+- [get-outlook-mail-failures.md](./get-outlook-mail-failures.md) — the read activity that produces the `MailMessage` items; shares the `Account`/shared-mailbox and COM-session surfaces, and is where the stale-reference window opens.
+- [move-outlook-mail-failures.md](./move-outlook-mail-failures.md) — the Move activity (the recommended in-loop alternative to deleting); shares the COM-session and New-Outlook surfaces.
+- [send-outlook-mail-failures.md](./send-outlook-mail-failures.md) — shares the COM-blocked / programmatic-access / privilege surface (branch 4 here).
+- [o365-activities overview](../../o365-activities/overview.md) — modern Microsoft Graph / OAuth mail delete; the required path on New Outlook and the preferred path for unattended deletes.
+- [mail-activities overview](../overview.md) — the package's connection model (Outlook desktop COM vs SMTP/protocol).