@uipath/skills 1.197.0 → 1.197.2

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/cs-dependency-unavailable.md

@@ -0,0 +1,59 @@
+---
+confidence: high
+---
+
+# Connection Service — Internal / Dependency Failure (CNS2003, CNS2005, CNS2006, CNS2007, CNS2009, CNS2010, CNS2012, CNS1042, CNS1101)
+
+> **Fault bucket: 🛠 B — service-side (not customer-fixable → retry, then escalate).** Every code on this page means Connection Service itself, or a dependency it calls (SQL, Orchestrator, Identity, the message bus, or the connector-provider layer), failed — **not** the customer's connection, credentials, or input. Lead with: "This is a service-side issue inside the platform — retry; if it persists, contact the owner team (Integration Service) with the `traceId`." The only split to make is **B1 vs B2**: `CNS1042`/`CNS1101` are the *third-party provider* failing (B2 — wait/retry), everything else is a *UiPath-internal* dependency (B1 — escalate if sustained). See [cns-error-codes-reference.md](../cns-error-codes-reference.md#fault-ownership).
+
+## Context
+
+What this looks like:
+- HTTP `5xx` (or `502`/`424` for the provider codes) from a Connection Service API call — creating/listing/pinging connections, managing triggers, or a connector activity resolving its connection at runtime
+- Error body shape: `{ "code": "CNS2007", "message": "Integration Service is currently unavailable. Please try again later.", "traceId": "…" }`
+- In App Insights (owner team): traces matching `Connection Service error reported: [StatusCode: …, ErrorCode: "CNS2xxx", …]`
+
+Code → failing dependency:
+
+| Code | Name | What failed | HTTP |
+|------|------|-------------|:---:|
+| `CNS2003` | DatabaseConnectionFailed | SQL database open/query (transient by definition) | 500 |
+| `CNS2005` | OrchestratorCallFailed | A Connection Service → **Orchestrator** API call (trigger CRUD, queue-definition / process lookups) returned an error | mirrors Orchestrator's status |
+| `CNS2006` | UnknownInternalError | Catch-all: an unhandled exception reached the global middleware | 500 |
+| `CNS2007` | ServiceUnavailableError | A downstream UiPath dependency answered **503** | 503 |
+| `CNS2009` | TokenRequestFailed | S2S token request to **Identity** failed (`invalid_client` or Identity outage) | mirrors Identity's status |
+| `CNS2010` | RequestTimeout | An outbound HTTP call (Orchestrator / provider layer / Identity) hit the client-side timeout | 500 |
+| `CNS2012` | MessageBusDispatchFailed | Dispatcher could not publish a trigger-fired event to the **message bus** | 503 |
+| `CNS1042` | CeExternalProviderError | The **third-party provider** behind the connector returned a 5xx ("Error from provider: …") | 502 |
+| `CNS1101` | VendorError | Provider-layer vendor error — the third-party service rejected or rate-limited the request (dependency failures surface as 424 FailedDependency; a vendor 429 also lands here) | 424 / 429 |
+| `CNS2001` | CEAccountCreationFailed | Provisioning the connector-platform shadow account for a UiPath identity failed | 503 |
+| `CNS2008` | DeleteCeUserFailed | Deleting the connector-platform user during account/tenant cleanup failed | 503 |
+| `CNS1036` | CEDeleteInstanceFailed | Deleting the connector-platform instance during connection delete failed | mirrors dependency status |
+
+What can cause it:
+- Transient dependency blips — SQL failovers, Orchestrator deploys, Identity token-endpoint hiccups, message-bus congestion. Most of these self-heal.
+- A genuine dependency incident (sustained `CNS2005`/`CNS2007` clusters across tenants).
+- For `CNS1042`/`CNS1101` — the third-party service (Salesforce, O365, …) itself is down or erroring; UiPath is only relaying it.
+- `CNS2010` with no other signal usually means one slow dependency call, not an outage.
+
+What to look for:
+- **Is it one request or a cluster?** A single occurrence that succeeds on retry is a transient blip. A sustained cluster (same code, many tenants, > ~15 min) is an incident.
+- **The `traceId` from the error body** — it is the correlation key the owner team needs; always capture it.
+- For `CNS1042`: the provider name in the message — check that provider's status page before escalating to UiPath.
+
+## Investigation
+
+1. **Do NOT chase the connection.** None of these codes indicate a credential, permission, or configuration problem. Re-authenticating the connection, editing it, or recreating it will not help — skip those steps.
+2. **Retry once.** All codes on this page except `CNS1101`-on-4xx are transient-classified (5xx/408/429 and the Db/Identity/MessageBus dependency family are auto-retried by background flows; interactive calls are not). A clean retry closes the case.
+3. **Classify B1 vs B2:**
+   - `CNS1042` / `CNS1101` → **B2** — read the provider name from the message and check the third-party service's status/health page. If the provider is degraded, wait it out.
+   - Everything else → **B1** — a UiPath-internal dependency. Check the UiPath status page / trust portal for a known incident in the tenant's region.
+4. **Establish blast radius (owner team):** in the Connection Service App Insights for the region, `union traces, exceptions | where customDimensions.ErrorCode == "CNS2xxx" | summarize count() by bin(timestamp, 15m)` — a flat low baseline is normal background noise; a step change marks an incident window. `CNS2005` also carries the Orchestrator status code in the message — 401/403 clusters point at S2S token/permission drift rather than an Orchestrator outage.
+5. **For `CNS2012` specifically** — trigger events are queued and retried by the dispatcher; a brief message-bus blip usually means delayed (not lost) trigger firings. Sustained failures = escalate; the events may be dropped after retry exhaustion.
+
+## Resolution
+
+- **Transient (single occurrence, retry succeeds):** no action. Note the `traceId` in case it recurs.
+- **`CNS1042` / `CNS1101` with a degraded provider:** wait for the third-party service to recover; nothing to fix on the UiPath side. If the provider is healthy and the code persists, escalate to Integration Service — the connector's provider integration may be broken.
+- **Sustained B1 (any other code):** escalate to the Integration Service owner team with: the CNS code, the `traceId`(s), tenant/org IDs, timestamps, and the affected operation (e.g. "trigger create", "connection ping"). These are platform faults; the customer cannot resolve them from their side.
+- **Never** advise the customer to delete/recreate connections or triggers for these codes — it does not address the dependency fault and can lose configuration.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/cs-events-callback-failed.md

@@ -0,0 +1,55 @@
+---
+confidence: medium
+---
+
+# Connection Service — Event Callback Processing Failed (CNS1005, CNS2000, CNS1015–CNS1019, CNS1024, CNS1029, CNS2011)
+
+> **Fault bucket: 🛠 B1 — service-side (machine-to-machine path; the customer never makes these calls).** These codes fire while Connection Service processes an **inbound event callback** from the connector platform (the webhook that says "an event happened on the third-party side"). The caller is the platform itself, not a user — so a bad payload, an orphaned instance, or a mismatched connection ID is a platform/data-drift issue. The **customer-visible symptom is a trigger that doesn't fire** (or fires late); triage the customer report via [trigger-not-firing.md](./trigger-not-firing.md) and use this page to interpret what the service-side codes mean.
+
+## Context
+
+What this looks like (owner-team view — App Insights traces, not customer errors):
+- `Connection Service error reported: [StatusCode: NotFound, ErrorCode: "CNS1005", ErrorReason: "Connection for element instance [N] was not found"]` — the single **highest-volume** CNS signal in production
+- `CNS2000` — *"Fail to handle notification"* — a 500 catch-all around event handling
+
+| Code | Name | Exact meaning | HTTP |
+|------|------|---------------|:---:|
+| `CNS1005` | ConnectionForElementInstanceNotFound | An event arrived for a provider-side element instance that maps to **no connection** — the connection was deleted but the provider-side subscription still delivers events (orphaned instance) | 404 |
+| `CNS2000` | EventsCallbackFailed | Unhandled exception while processing the event callback | 500 |
+| `CNS1015` | EventsCallbackInstanceIdMissing | Callback payload missing the instance ID | 400 |
+| `CNS1016` | EventsCallbackHasMoreThanOneEvent | Callback carried more than one event (unsupported shape) | 400 |
+| `CNS1017` | ObjectTypeMissing | Callback payload missing object name/type | 400 |
+| `CNS1018` | EventsInfoMissing | Callback payload missing the events section | 400 |
+| `CNS1019` | EventTypeMissing | Callback payload missing the event type | 400 |
+| `CNS1024` | EventsCallbackRequestInvalid | Callback body null/unparsable JSON | 400 |
+| `CNS1029` | EventsCallbackInvalidConnectionId | Connection ID in the callback route doesn't match the instance's actual connection | 400 |
+| `CNS2011` | EventTypeUtilFailed | No matching event operation/mode/type registered for the connector event key — event-catalog mapping gap | 400 |
+
+Related codes on the *outbound* side of the same pipeline: `CNS1011`/`CNS1012`/`CNS1013` (connection-event create/delete validation — duplicate registration, missing IDs) are low-volume request-validation errors on event-configuration APIs; fix the request. Event *dispatch* to downstream products failing is `CNS2012` — see [cs-dependency-unavailable.md](./cs-dependency-unavailable.md).
+
+What can cause it:
+- **`CNS1005` steady-state noise:** connections deleted while the provider-side event subscription lives on for a while — expected background volume, mostly benign; each hit is a dropped event for a connection that no longer exists
+- Malformed or truncated payloads from the connector platform / provider (the `CNS101x` family)
+- Connector catalog/event-registration drift (`CNS2011`, and `CNS2045` — see [cs-connector-unavailable.md](./cs-connector-unavailable.md))
+- Genuine processing bugs or downstream failures inside event handling (`CNS2000`)
+
+What to look for:
+- **Volume shape, not single hits.** A flat baseline of `CNS1005` is normal; a step-change spike (or a cluster on one tenant/connector) is an incident or a mass-deletion side effect
+- Whether a specific connector dominates the failures (points at that connector's payload shape or event registration)
+- For a customer-reported missing trigger event: whether their connection was recently deleted/recreated (the old instance still emitting → events land on the orphan, new connection gets nothing until re-subscription)
+
+## Investigation
+
+1. **Start from the customer symptom** ("trigger didn't fire") with [trigger-not-firing.md](./trigger-not-firing.md) — verify the trigger, connection state, and event subscription first.
+2. **Owner team — locate the callback failures:** in the region's Connection Service App Insights, `union traces, exceptions | where message has "CNS1005" or customDimensions.ErrorCode in ("CNS1005","CNS2000","CNS1029") | summarize count() by tostring(customDimensions.ErrorCode), bin(timestamp, 1h)` and segment by tenant/connector to find clusters.
+3. **`CNS1005` for a specific complaint:** match the element-instance number in the message against the customer's connection history — if the events target a deleted connection's instance, the fix is re-establishing the subscription on the *new* connection (usually recreating the trigger), not chasing the 404s.
+4. **`CNS101x` payload-shape codes:** capture a sample payload (owner team) and identify the sending connector — this is a defect report against the connector/platform event pipeline, not something to work around per-customer.
+5. **`CNS2000`:** read the wrapped inner exception in the trace — it is a catch-all; classify the real cause (DB? downstream? mapping?) and route accordingly.
+
+## Resolution
+
+- **Customer-facing:** if events stopped after a connection was recreated, recreate/re-save the trigger so the event subscription binds to the new connection instance. Verify a test event flows end-to-end.
+- **`CNS1005` background noise:** no action per-hit. Sustained high volume from one tenant is worth a cleanup (delete stale provider-side subscriptions) — an owner-team/ops action.
+- **Payload-shape and mapping codes (`CNS101x`, `CNS2011`):** escalate to the Integration Service owner team with connector key, sample `traceId`s, and the earliest occurrence — these are connector/platform defects.
+- **`CNS2000` clusters:** treat as a service incident — escalate with the inner-exception signature and time window.
+- **Never** advise customers to retry or re-authenticate for these codes — the failing call is machine-to-machine; nothing on the customer side retries it.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/cs-operation-conflict.md

@@ -0,0 +1,41 @@
+---
+confidence: high
+---
+
+# Connection Service — Conflict / Duplicate (CNS3002, CNS1007, CNS1038)
+
+> **Fault bucket: 👤 A for `CNS1038` (pick another name) · 🛠 mixed for `CNS1007` (usually a create race — retry once) · 🔧 ops-tooling for `CNS3002` (an internal migration/backfill is already running — wait or deliberately override; never a customer action).** Everything here is a *state collision*, not a fault: something already exists or is already running.
+
+## Context
+
+What this looks like:
+
+| Code | Name | Exact meaning | HTTP | Who acts |
+|------|------|---------------|:---:|---|
+| `CNS3002` | Conflict | A single-flight lock is held: an in-progress **tenant migration**, **Orchestrator-trigger migration** (`migrate-disconnected`), or **personal-workspace backfill** job is already running for the tenant, and a second trigger attempt arrived without the override flag | 409 | Ops / owner team |
+| `CNS1007` | ConnectionKeyOrIndexViolation | Duplicate-key violation inserting a connection — two concurrent creates of the same connection, or a retry racing its original | 400 | Customer (retry) / service if persistent |
+| `CNS1038` | ConnectionNameDuplicated | Rename rejected — *"The name is already in use."* | 400 | Customer |
+
+Related 409: `CNS1075` (connector not deployed) also surfaces as 409 but is a connector-deployment fault — see [cs-connector-unavailable.md](./cs-connector-unavailable.md).
+
+What can cause it:
+- `CNS3002`: a previous migration/backfill run is still in progress — or crashed while holding its lock (stuck lock). The message names the job type (e.g. an `OrchTrigger` migration record).
+- `CNS1007`: double-submit on connection creation (UI double-click, client retry without idempotency), or parallel automation creating the same connection
+- `CNS1038`: straightforward — the target name exists in scope
+
+What to look for:
+- `CNS3002`: **is the named job actually running?** A genuinely running job → wait. No live job but the lock persists → stuck lock from a crashed run.
+- `CNS1007`: whether the connection actually got created despite the error (the race's winner) — often the retry fails but the resource exists
+
+## Investigation
+
+1. **`CNS3002`:** identify the job family from the message (GWS tenant migration / OrchTrigger migration / PWs backfill). Owner team: check the job's progress records and task-runner logs for a live run. If the last run terminated abnormally and the lock is stale, the trigger API accepts an explicit override flag (`OverrideMigrationInProcess` / `OverrideJobInProcess` / `OverrideBackfillInProcess`) — an **ops decision**: only override when certain no run is in flight, since overriding overwrites the live migration record.
+2. **`CNS1007`:** list connections for the connector/folder — if the intended connection exists, the create actually succeeded on the other racer; use it. If nothing exists and the error repeats on clean single-flight creates, capture the `traceId` and escalate (persistent key collision is a service defect).
+3. **`CNS1038`:** nothing to investigate — enumerate existing names.
+
+## Resolution
+
+- **`CNS3002` with a live job:** wait for completion; the lock releases itself. Do not spam the trigger endpoint.
+- **`CNS3002` with a stuck lock:** ops re-fires the trigger with the override flag — on the **first** batch/attempt only; never override while a run is legitimately in flight.
+- **`CNS1007`:** retry the create once; if the connection appeared, deduplicate client-side (avoid double-submit). Persistent → escalate with `traceId`.
+- **`CNS1038`:** choose a unique connection name. Name-length/empty variants of the same rename validation surface as `CNS1032`/`CNS1033`.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/cs-permission-denied.md

@@ -0,0 +1,54 @@
+---
+confidence: high
+---
+
+# Connection Service — Permission / Authorization Denied (CNS1045, CNS1044, CNS1046, CNS1047, CNS1043, CNS3001)
+
+> **Fault bucket: 👤 A — customer/admin-resolvable.** The caller reached Connection Service but was rejected by an authorization layer: missing **folder permission** (the big one — `CNS1045`), missing OAuth **scope**, a client ID not allowed on the endpoint, a bad/unsupported token, or an **Automation Ops governance policy** blocking the connector. In every case the fix is an admin action (grant permission/scope, adjust policy) — not a retry and not a service escalation.
+
+## Context
+
+What this looks like:
+- HTTP `403`/`401` (or `400` for the missing-folder-key case) from Connection Service
+- The highest-volume production signature: `CNS1045` — *"The robot does not have the Connections.View permission in the folder where this connection lives. Ask your administrator to grant Connections.View on that folder, or move the connection to a folder where the robot has the required permission."* (sometimes with a `(Folder: <key>)` hint)
+- Debug runs work (user identity has the permission) but deployed/unattended runs fail (robot account doesn't) — the classic signature of a folder-permission gap
+
+| Code | Name | Rejecting layer | Exact meaning | HTTP |
+|------|------|-----------------|---------------|:---:|
+| `CNS1045` | InsufficientFolderPermission | Folder authorization | Caller lacks a folder-scoped permission (default named permission: `Connections.View`) on the folder holding the connection/trigger | 403 |
+| `CNS1044` | InsufficientPermissions | Scope authorization | The token lacks a required OAuth scope; also used when a downstream dependency answers 403 | 403 |
+| `CNS1046` | InsufficientClientId | Client authorization | The token's `client_id` is not on the endpoint's allow-list (S2S/internal endpoints) | 401 |
+| `CNS1047` | Unauthorized | Authentication | Token invalid/wrong audience; also *"External application authentication is not supported"* on endpoints that don't accept external-app tokens | 401 |
+| `CNS1043` | MissingFolderKey | Request validation | An S2S caller did not supply the folder key that folder-scoped resolution requires | 400 |
+| `CNS3001` | ForbiddenAccess | Governance | An **Automation Ops policy** blocks the action — e.g. *"The connector was disabled by an Automation Ops policy."* Fires on connection create and re-authenticate when the policy denies the connector | 403 |
+
+Related: `CNS1025` — nominally "TriggerRequestInvalid" — is **reused** for *"In S2S context, the folder key is required"* on several connection/trigger endpoints. Treat that message the same as `CNS1043` regardless of the code.
+
+What can cause it:
+- Robot account was never granted `Connections.View` (or the folder-specific permission the message names) on the folder the connection lives in
+- The connection was moved to a different folder after the process was deployed
+- API/external-app integration was registered without the Connection Service scopes it calls
+- An Automation Ops governance policy was tightened, disabling a connector tenant-wide or for specific groups
+- Internal S2S callers omitting the folder key header/parameter after an integration change
+
+What to look for:
+- **Which permission and which folder** — the `CNS1045` message names the permission and often the folder key; that's the exact grant to make
+- Caller identity: user vs robot account vs external app (the fix target differs)
+- For `CNS3001`: which policy — check Automation Ops policies applied to the tenant/user group for the named connector
+
+## Investigation
+
+1. **Read the message, not just the code** — `CNS1045` tells you the missing permission and (usually) the folder. That is 90% of the diagnosis.
+2. **Identify the caller identity** the request ran under (robot account for unattended jobs, the user for debug, the app registration for API calls). Verify in Orchestrator → Folders → the named folder → Assigned users/robots whether that identity holds the named permission (e.g. `Connections.View`; Maestro trigger paths may also need `Triggers` permissions).
+3. **Reproduce the split**: if debug works and deployed fails, it is a robot-account grant, full stop.
+4. **`CNS1044`/`CNS1047` on API integrations**: inspect the token (scopes, audience). For external apps, confirm the app registration includes the Integration Service / Connection Service scopes it invokes and that the endpoint supports external-app tokens at all (`CNS1047`'s "not supported" message means it never will — use a different auth model).
+5. **`CNS3001`**: list Automation Ops policies for the tenant; find the connector allow/deny list that covers the affected user/group. The connection UI action that failed (create or re-authenticate) confirms the policy is evaluated on those flows.
+6. **`CNS1043` / folder-key-required `CNS1025`**: only surfaces on S2S/machine callers — a missing folder key in the request. This is an integration bug in the *calling service*, not a permissions grant.
+
+## Resolution
+
+- **`CNS1045`:** have a folder admin grant the named permission (typically `Connections.View`) to the robot/user on the folder holding the connection — or move the connection to a folder where the runner already has it. Re-run; no re-authentication needed.
+- **`CNS1044`:** add the missing OAuth scope to the app registration / token request. If it wrapped a downstream 403, treat the named dependency's permission model (e.g. Orchestrator role) instead.
+- **`CNS1046`/`CNS1047`:** these are integration-configuration rejections — fix the token audience/client registration; do not retry with the same token. `CNS1046` on UiPath-internal endpoints reaching a customer is unusual — capture the `traceId` and escalate if the caller is a supported public surface.
+- **`CNS3001`:** a governance decision, not an error — the admin either updates the Automation Ops policy to allow the connector or the user stops using the blocked connector. Never escalate to Integration Service to "fix" a policy block.
+- **`CNS1043` / S2S folder key:** fix the calling integration to pass the folder key. If the caller is a UiPath product (not customer code), escalate to that product's team with the `traceId`.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/cs-solutions-install-failed.md

@@ -0,0 +1,66 @@
+---
+confidence: medium
+---
+
+# Connection Service — Solutions Package Install / Validation Failed (CNS1050, CNS1055–CNS1075 range, shell connections)
+
+> **Fault bucket: 👤 A for spec/version/authentication issues (the package author or installer fixes the package or the tenant state) · 🛠 B1 for unexpected-error and stuck-publish codes.** These codes surface when a **Solutions package** that carries connections/connectors is validated or installed into a tenant. Unlike the rest of the CNS family, most of them are **not HTTP errors** — they arrive *embedded* in the validation response (`ValidateResourcesResponse`) or the async install job's status as per-resource `ValidationError` entries, each with its own `ErrorCode` and sometimes `AllowedActions`.
+
+## Context
+
+What this looks like:
+- Solution install/validate reports per-resource errors; the install job status carries `ValidationError { ErrorCode: "CNS10xx", … }` entries
+- A corrupt package upload fails outright with HTTP 400 `CNS1050`
+
+Package/spec validation (fix the package):
+
+| Code | Name | Meaning | Action |
+|------|------|---------|--------|
+| `CNS1050` | InvalidSolutionArchive | Package zip is corrupt/unreadable (HTTP 400, not embedded) | Rebuild/re-upload the package. ⚠ `CNS1050` is a **duplicated literal** — it is also `EventModeNotSupported` on the make-connection-call API; disambiguate by operation. |
+| `CNS1059` | ConnectorKeyRequired | Connector/connection resource spec missing `Key` | Fix package spec |
+| `CNS1074` | ConnectorNameRequired | Connector spec missing `Name` | Fix package spec |
+| `CNS1055` | InvalidAuthenticationType | Connection spec has an unrecognized authentication type | Fix package spec |
+| `CNS1058` | ConnectionNameInvalid | Connection spec name invalid | Fix package spec |
+| `CNS1039` | InvalidPollingInterval | Polling interval out of range (also a live-API error) | Fix package spec |
+
+Connector version reconciliation (installer chooses):
+
+| Code | Name | Meaning | AllowedActions |
+|------|------|---------|----------------|
+| `CNS1064` | ConnectorVersionNotFound | Package links a custom-connector version not present in the tenant | Install the connector first |
+| `CNS1066` | LowerConnectorVersionExists | Tenant has a lower version than the package expects | UseExisting / MergeConfiguration |
+| `CNS1067` | HigherConnectorVersionExists | Tenant has a higher version | UseExisting |
+
+Shell connections (authenticate-after-deployment):
+
+| Code | Name | Meaning | Action |
+|------|------|---------|--------|
+| `CNS1068` | ShellConnectionRequired | Spec says authenticate-after-deployment but no shell-connection key supplied | Fix package spec |
+| `CNS1069` | ShellConnectionNotFound | Referenced shell connection doesn't exist in the tenant | Create/fix the reference |
+| `CNS1072` | ShellConnectionRequiredAuthentication | Shell connection exists but is unauthenticated | Authenticate it, then install |
+| `CNS1071` | ShellConnectionWarning | Informational: authentication will be required after deployment | None — expected |
+| `CNS1070` | ShellConnectionUnexpectedError | Unexpected failure validating the shell connection | 🛠 escalate |
+
+Service-side install failures (escalate if not transient):
+
+| Code | Name | Meaning |
+|------|------|---------|
+| `CNS1060` | ConnectorKeyUnexpectedError | Unexpected exception checking connector existence/version (element-service call failure) |
+| `CNS1063` | ConnectorImportError | Unexpected exception importing a custom connector, or its publish job failed |
+| `CNS1065` | ConnectorImportPublishError | Connector publish job stuck in progress past the polling timeout |
+| `CNS1056` | ConnectionCreateError | Unexpected exception creating a connection during install |
+| `CNS1057` | ConnectionUpdateError | Unexpected exception updating a connection during install |
+
+## Investigation
+
+1. **Read the per-resource `ValidationError` list from the install/validate response** — each entry names the resource, the code, and (for version conflicts) the `AllowedActions`. The code table above routes each one; most installs fail on the *first* category (spec errors) or the *second* (version reconciliation).
+2. **Version conflicts (`CNS1064`/`CNS1066`/`CNS1067`)** are choices, not faults: decide whether the tenant's existing connector version should win (`UseExisting`), merge configuration, or install the packaged version first.
+3. **Shell-connection codes:** verify the referenced connection exists and is authenticated in the target tenant *before* re-running the install. `CNS1071` is a warning — the install proceeded; someone must authenticate after deployment (until then, runtime calls will fail with `CNS1008` — see [cs-connection-not-authenticated.md](./cs-connection-not-authenticated.md)).
+4. **Service-side codes (`CNS1060`/`CNS1063`/`CNS1065`/`CNS1056`/`CNS1057`):** retry the install once (transient dependency blips are common); a repeat with the same code is an Integration Service escalation with the install job ID and `traceId`. `CNS1065` specifically means the connector publish pipeline is slow/stuck — check for a wider publish backlog before blaming the package.
+
+## Resolution
+
+- **Spec errors:** fix the package definition and rebuild — these never self-resolve.
+- **Version reconciliation:** pick an `AllowedAction` deliberately; document which connector version the solution standardizes on to avoid drift across tenants.
+- **Shell connections:** create/authenticate the referenced connection, re-run install; plan for post-deployment authentication of `CNS1071`-flagged connections as part of the rollout runbook.
+- **Sustained service-side failures:** escalate with install job ID, tenant, package name/version, and `traceId`s.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/cs-trigger-operation-failed.md

@@ -0,0 +1,48 @@
+---
+confidence: high
+---
+
+# Connection Service — Trigger Management Failed (CNS1020, CNS1014, CNS1025, CNS1039, CNS2004)
+
+> **Fault bucket: 👤 A for `CNS1020`/`CNS1014`/`CNS1039` and most `CNS1025` (bad ID, blocked delete, bad interval, malformed request) · 🛠 B1 for `CNS2004` (persisted trigger configuration cannot be deserialized — a data/platform defect).** These codes fire on trigger CRUD — create, rename, enable/disable, convert, delete — via the Connection Service API. For a trigger that manages fine but silently doesn't *fire*, use [trigger-not-firing.md](./trigger-not-firing.md) instead; for enable failing because the underlying connection is dead, it's `CNS1061` in [cs-connection-not-authenticated.md](./cs-connection-not-authenticated.md).
+
+## Context
+
+What this looks like:
+- HTTP `400`/`404` from trigger endpoints, error body `{ "code": "CNS1020", "message": "Trigger [<guid>] is invalid or you do not have access…", "traceId": "…" }`
+
+| Code | Name | Exact meaning | HTTP | Bucket |
+|------|------|---------------|:---:|:---:|
+| `CNS1020` | TriggerIdInvalid | Trigger ID doesn't exist / caller has no access — or the trigger isn't of the type the operation requires (e.g. convert/migrate on a non-automation trigger) | 404 | 👤 A |
+| `CNS1014` | DeleteTriggerWithActiveProcessNotAllowed | Delete blocked: the trigger still has active/assigned processes | 400 | 👤 A |
+| `CNS1025` | TriggerRequestInvalid | Malformed trigger request — **heavily overloaded**: missing body fields, *"In S2S context, the folder key is required"* (also thrown by some connection endpoints), and one service-side notification-failure branch | 400 (one 500 branch) | 👤 A (mostly) |
+| `CNS1039` | InvalidPollingInterval | Polling interval outside the allowed min/max range | 400 | 👤 A |
+| `CNS2004` | TriggerConfigDeserializationFailed | The trigger's persisted configuration blob can't be deserialized / has an unknown trigger type — data corruption or version drift | 500 | 🛠 B1 |
+
+What can cause it:
+- Automations/scripts referencing trigger IDs that were deleted or belong to another folder/tenant
+- Attempting to delete a trigger still wired to processes (`CNS1014` is a guard, not a fault)
+- S2S/machine callers omitting the folder key after an integration change (`CNS1025`)
+- Setting polling intervals below the tenant minimum (`CNS1039`)
+- `CNS2004`: a trigger created by an older service version whose config schema the current version can't read, or a corrupted row — never customer-caused
+
+What to look for:
+- The trigger GUID and which operation failed (create/update/state-change/delete/convert)
+- `CNS1025`: read the message — "folder key is required" vs a field-validation message vs anything else; the code alone does not identify the failure
+- `CNS2004`: which trigger ID — the same trigger will fail deterministically on every read/fire until repaired
+
+## Investigation
+
+1. **Resolve the trigger** in the tenant (Integration Service → Triggers, or via API list) — confirm existence, folder, and type. `CNS1020` on convert/migrate operations can mean "exists but wrong trigger type", which the message indicates.
+2. **`CNS1014`:** list the processes attached to the trigger; that list is the blocker. This is working-as-designed protection.
+3. **`CNS1025`:** classify by message. Folder-key-required → fix the S2S caller (see [cs-permission-denied.md](./cs-permission-denied.md) for the same pattern under `CNS1043`). Field validation → fix the request payload. Anything mentioning notification/SAP with a 500 → treat as service-side, capture `traceId`, escalate.
+4. **`CNS2004`:** deterministic 500 on a specific trigger = data-level defect. Do not loop retries. Capture the trigger ID and `traceId` and check whether the trigger predates a known migration; the owner team repairs or migrates the config.
+5. If trigger *creation* fails with an Orchestrator-related error rather than these codes, the failing leg is Connection Service → Orchestrator (`CNS2005`) — route to [cs-dependency-unavailable.md](./cs-dependency-unavailable.md).
+
+## Resolution
+
+- **`CNS1020`:** correct the trigger reference (recreate the trigger or point the caller at the right ID/folder); for type-mismatch variants, run the operation against a trigger of the required type.
+- **`CNS1014`:** unassign/stop the attached processes first, then delete the trigger — or keep the trigger if the processes are still needed.
+- **`CNS1025` (customer variants):** fix the request — supply the folder key on S2S calls, complete required fields.
+- **`CNS1039`:** set the polling interval within the documented range for the tenant/connector.
+- **`CNS2004`:** escalate to the Integration Service owner team with trigger ID + `traceId`. Deleting and recreating the trigger is a customer-side workaround *only if* losing the trigger's history/config is acceptable — offer it, don't default to it.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/http-client-exception.md

@@ -0,0 +1,44 @@
+---
+confidence: high
+---
+
+# HTTP Client Exception (DAP-RT-1103)
+
+> **Fault bucket: 🛠 B2 — Service/provider-side (not customer-fixable in the workflow → escalate).** A network-level failure between the robot and UiPath's Integration Service endpoint. On self-hosted robots the customer owns the egress path (firewall/proxy/DNS) — that part is theirs to fix; it is never a workflow change. On UiPath-hosted cloud robots there is no customer-side network to fix — escalate. Lead with: "This is a connectivity issue between the robot and UiPath's cloud, not a workflow bug — check network egress or escalate." See [dap-error-codes-reference.md](../dap-error-codes-reference.md#fault-ownership--the-two-bucket-decision).
+
+## Context
+
+**What the target host is:** the connector request goes from the activity runtime (robot) to **UiPath's Integration Service endpoint** in Automation Cloud — the connection's `ApiBaseUri`, shaped like `https://cloud.uipath.com/<org>/<tenant>/elements_`. IS then calls the vendor API on the robot's behalf. `DAP-RT-1103` means the runtime could not reach the **UiPath endpoint**; a vendor-side failure returns an HTTP status through IS and surfaces as `DAP-RT-1101` instead.
+
+What this looks like:
+- Error code `DAP-RT-1103` (HttpClientException)
+- Network-level failure — no HTTP status returned (exception before/without a response)
+- `ProviderErrorCode` absent (the request never got a response)
+- Maps to the `retry-exception` SRE alert when retries are exhausted
+
+What can cause it:
+- DNS cannot resolve the UiPath cloud host from the robot machine
+- Firewall/proxy blocks outbound traffic to UiPath cloud domains — see [Configuring the firewall](https://docs.uipath.com/automation-cloud/automation-cloud/latest/admin-guide/configuring-firewall) for the domains and outbound IP ranges to allowlist
+- TLS handshake failure — usually an SSL-inspecting corporate proxy re-signing the certificate, or a stripped trust store on the robot machine
+- Request timeout to the IS endpoint, or a transient blip — absorbed by IS's automatic retry (max 2 attempts, jittered backoff; see [Retry semantics](../dap-error-codes-reference.md#retry-semantics)) unless sustained
+
+What to look for:
+- Absence of `ProviderErrorCode` — distinguishes this from `DAP-RT-1101` (a status was returned)
+- Whether `retry-exception` fired — retries exhausted means sustained connectivity failure, not a blip
+- **Where the job ran** — UiPath-hosted cloud robot (UiPath-managed network → escalate) vs self-hosted robot (customer machine/VM; customer owns DNS/firewall/proxy egress)
+- `RequestId` to correlate timing across the call
+
+## Investigation
+
+1. **Confirm it is network-level, not provider-level** — verify `ProviderErrorCode` is absent. If a status is present, use [request-failed.md](./request-failed.md) instead.
+2. **Read the connection resource file** — identify the connector and connection (see "Connection Resource File" in [overview.md](../overview.md)).
+3. `uip is connections ping <connection-id>` — if ping also fails at the network layer, the problem is connectivity, not the operation.
+4. **Determine the runtime environment** — the machine the job executed on (from the job's host identity): self-hosted robot / unattended machine vs UiPath-hosted cloud robot. Self-hosted egress rules differ from a developer's machine — debug may succeed where deployed fails.
+5. On self-hosted robots: check the UiPath cloud host resolves and is reachable from that machine (DNS, firewall egress, proxy).
+
+## Resolution
+
+- **Self-hosted robot — DNS / firewall / proxy:** allowlist the UiPath cloud domains and outbound IP ranges from the robot's network, and configure proxy settings on the robot machine if required. Follow [Configuring the firewall](https://docs.uipath.com/automation-cloud/automation-cloud/latest/admin-guide/configuring-firewall).
+- **Self-hosted robot — TLS:** if a corporate proxy performs SSL inspection, install/trust the proxy's CA on the robot machine or exclude UiPath cloud domains from inspection.
+- **UiPath-hosted cloud robot:** no customer-side network to fix — escalate to UiPath support with the `DAP` code, `RequestId`, and timestamp.
+- **Sustained `retry-exception`:** retries are already exhausted; application-level retry will not help. Route to whoever owns network egress (customer network team for self-hosted; UiPath for cloud robots).

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/missing-required-input.md

@@ -0,0 +1,38 @@
+---
+confidence: high
+---
+
+# Missing Required Input (DAP-RT-1003 / DAP-RT-1007)
+
+> **Fault bucket: 👤 A — Customer-resolvable.** A required input value the activity needs was not supplied. The customer fixes it by providing the value. Lead with: "This is an input/configuration issue on your side — provide the missing field." See [dap-error-codes-reference.md](../dap-error-codes-reference.md#fault-ownership--the-two-bucket-decision).
+
+## Context
+
+What this looks like — IS rejected the call before reaching the provider because a required input was empty:
+
+| Code | Name | Specific cause |
+|---|---|---|
+| `DAP-RT-1003` | ArgumentIsRequired | A required input argument is missing |
+| `DAP-RT-1007` | PropertyIsRequired | A required property is empty |
+
+What can cause it:
+- A required activity input was left unbound or bound to an empty/null variable
+- An upstream step produced no value, leaving the required input empty at runtime
+- The activity was published with a required field unset
+
+What to look for:
+- No `ProviderErrorCode` / provider status — the failure is input validation, before any provider call
+- `ErrorMessage` naming the specific argument/property that is required
+- Whether the input is bound to an expression that can resolve to empty/null
+
+## Investigation
+
+1. **Read `ErrorMessage` from the customEvent** — it names the missing argument or property. That is the field to fix.
+2. **Read the workflow source** — open the failing activity and check the named input: is it unbound, bound to an empty literal, or bound to a variable that can be null/empty at runtime?
+3. **Trace the value upstream** — if the input is bound to a variable, confirm the step that sets it actually produces a value on every path.
+
+## Resolution
+
+- **Unbound / empty literal:** provide the required field value on the activity, then republish.
+- **Bound to a variable that resolves empty:** fix the upstream step so the variable is always populated, or add a guard that supplies a default before the activity runs.
+- After the fix, re-run to confirm the input-validation error clears.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/request-failed.md

@@ -0,0 +1,49 @@
+---
+confidence: high
+---
+
+# Request Failed (DAP-RT-1101)
+
+> **Fault bucket:** depends on `ProviderErrorCode`. 4xx auth/input (`401`/`403`/`404`/`400`/`422`) → **👤 Bucket A** (customer fixes credentials/permissions/input). `429`/`5xx` → **🛠 Bucket B2** (provider-side outage/rate-limit — wait/retry, escalate if sustained). Always split on the status code before answering. See [dap-error-codes-reference.md](../dap-error-codes-reference.md#fault-ownership--the-two-bucket-decision).
+
+## Context
+
+What this looks like:
+- Error code `DAP-RT-1101` (RequestFailed) — the most common IS runtime failure
+- A `ProviderErrorCode` / provider status is present — the connector's downstream API returned an error (a downstream provider response, not an IS-side exception; there is no `IsServiceError` field to read)
+- Maps to the `http-4xx` / `retry-exception` SRE alerts
+
+The DAP code alone does not name the root cause — **the `ProviderErrorCode` (the 3rd-party API's own status) does.** Route on it:
+
+| Provider status | Meaning | Direction |
+|---|---|---|
+| 401 | Token rejected by the provider | Auth — the connection's OAuth token is expired/revoked; re-authenticate (see [connection-auth-expired.md](./connection-auth-expired.md)) |
+| 403 | Authenticated but not permitted | Connection scope/permissions too narrow for the operation |
+| 404 | Object/record not found | Input references a resource that does not exist in the external service |
+| 429 | Rate limited | Quota exceeded — retries (max 2) already exhausted |
+| 5xx | Provider outage | Transient on the provider side; retries exhausted = sustained outage |
+
+What to look for:
+- `ProviderErrorCode` + `ProviderErrorMessage` in the customEvent — the decisive evidence
+- `RequestId` — correlates the IS call to the connector log
+- Whether the same operation worked before (regression vs misconfiguration)
+- Whether a `retry-exception` alert fired — means 429/5xx retries were exhausted (sustained, not a blip)
+
+## Investigation
+
+1. **Read `ProviderErrorCode` / `ProviderErrorMessage` from the customEvent first.** This is the classifier — do not draw conclusions from `DAP-RT-1101` alone.
+2. **Read the connection resource file** — if source code is available, find the connection JSON (see "Connection Resource File" in [overview.md](../overview.md)) to get the connector name, connection ID, and `authenticationType`.
+3. `uip is connections ping <connection-id>` — confirm the connection itself is active (rules out auth-vs-operation).
+4. Branch on `ProviderErrorCode`:
+   - **401:** the connection's OAuth token was rejected by the provider — re-authenticate the connection (see [connection-auth-expired.md](./connection-auth-expired.md)). If ping is healthy but the provider still returns 401, the granted scope is wrong. (Note: `DAP-GE-3004` is unrelated — it is a first-party-service token failure, not a connection token; see [token-refresh-failed.md](./token-refresh-failed.md).)
+   - **403:** `uip is resources describe <connector-key> <object-name>` — check the operation's required permissions/scopes against what the connection was granted.
+   - **404:** verify the record/object ID in the activity input exists in the external service.
+   - **429/5xx:** check `RequestId` against the provider's status; if `retry-exception` fired, retries were exhausted.
+
+## Resolution
+
+- **401:** re-authenticate the connection (`uip is connections edit <connection-id>`). If the granted OAuth scope is insufficient, recreate the connection requesting the scope the operation needs.
+- **403:** widen the connection's scope or grant the external account the permission the operation requires, then re-authenticate.
+- **404:** correct the activity input to reference an existing record/object; guard upstream steps that produce the ID.
+- **429:** reduce call frequency, add backoff/batching, or request a higher provider quota. IS already retried twice — application-level pacing is required.
+- **5xx:** transient provider outage — retry later. If sustained (`retry-exception`), escalate to the provider; do not treat as a workflow bug.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/response-mapping-mismatch.md

@@ -0,0 +1,43 @@
+---
+confidence: medium
+---
+
+# Response Mapping Mismatch (DAP-RT-1005 / DAP-RT-1155 / DAP-RT-1156)
+
+> **Fault bucket: 🛠 B1 — IS platform / connector defect (escalate to owner team).** The provider returned data but the connector's declared output schema no longer matches it (connector schema drift). No provider error status — the mapping fails inside IS after a successful call. The customer cannot fix connector metadata; updating the activity package to a matching version is the only customer-side mitigation. Lead with: "This is a connector schema-drift issue on the service side — update the activity package if a matching version exists, otherwise contact the owner team (Integration Service)." See [dap-error-codes-reference.md](../dap-error-codes-reference.md#fault-ownership--the-two-bucket-decision).
+
+## Context
+
+What this looks like — the provider call succeeded but IS could not map the response into the activity's output type:
+
+| Code | Name | Specific cause |
+|---|---|---|
+| `DAP-RT-1005` | ApiResponseMismatch | Response shape doesn't match the activity's output type — connector schema drift |
+| `DAP-RT-1155` | DataTableFieldTypeMismatch | A response field's type doesn't match the expected TypedDataTable column |
+| `DAP-RT-1156` | TypedDataTableNotConstructedProperly | Output could not be assembled into the expected TypedDataTable |
+
+What can cause it:
+- The connector's response schema changed (provider API version drift) but the workflow's activity package is older
+- The activity's declared output type no longer matches what the provider returns
+- A field returned as a different type than the TypedDataTable column expects (e.g. string where a number is mapped)
+
+Concrete scenario (`DAP-RT-1005`): a workflow was published months ago with a Salesforce activity package whose "Get Record" output declares `AnnualRevenue` as a number. The vendor (or a connector schema update) now returns that field as a string, or renames/removes it. Every run since: the provider call itself succeeds (HTTP 200, data returned), but IS fails to deserialize the payload into the activity's generated output type — the job faults at the mapping step with no provider error. Nothing changed in the workflow; the schema drifted underneath it. The same shape triggers `1155`/`1156` when the drifted field feeds a TypedDataTable column.
+
+What to look for:
+- No provider error status — the failure is IS-side mapping, not a provider error (the call returned data)
+- The activity package version vs the current connector schema (drift is the usual cause of `1005`)
+- `ProviderErrorMessage` is typically absent — the provider returned 200; mapping failed afterward
+
+## Investigation
+
+1. **Confirm it is a mapping failure, not a provider error** — there should be no `ProviderErrorCode` / provider status. If a provider status is present, use [request-failed.md](./request-failed.md).
+2. **Read the connection resource file** — identify the connector and connection (see "Connection Resource File" in [overview.md](../overview.md)).
+3. `uip is resources describe <connector-key> <object-name>` — get the current field definitions and compare against the activity's declared output type.
+4. `uip is activities list <connector-key>` — check whether the activity/package version in the project lags the current connector schema.
+
+## Resolution
+
+- **`DAP-RT-1005` — schema drift:** update the connector activity package in the project to the version that matches the current response schema, then re-map the output and republish.
+- **`DAP-RT-1155` — field type mismatch:** correct the TypedDataTable column type to match the field returned by `uip is resources describe`, or transform the field before mapping.
+- **`DAP-RT-1156`:** re-create the output mapping from the current schema so the TypedDataTable is constructed from valid columns.
+- If the provider genuinely changed its contract, align the activity configuration to the new schema rather than forcing the old mapping.

package/skills/uipath-troubleshoot/references/products/integration-service/playbooks/token-refresh-failed.md

@@ -0,0 +1,42 @@
+---
+confidence: high
+---
+
+# Token Refresh Failed (DAP-GE-3004)
+
+> **Fault bucket: 🛠 B1 — IS platform / service-side (not customer-fixable → escalate).** `DAP-GE-3004` is IS failing to obtain an access token it needs to call a **first-party UiPath service** (e.g. Orchestrator, the Feature Flag service) while executing the activity. **This token is NOT the customer's connection credential** — it is issued by the platform for the first-party service, so re-authenticating the connection does nothing. Lead with: "This is a service-side token issue inside the platform, not your connection — retry; if it persists, contact the owner team (Integration Service)." See [dap-error-codes-reference.md](../dap-error-codes-reference.md#fault-ownership--the-two-bucket-decision).
+
+## Context
+
+What this looks like:
+- Error code `DAP-GE-3004` (FailedToGetAccessToken)
+- IS could not obtain an access token for a **first-party UiPath service** it calls at runtime (Orchestrator, Feature Flag service, …) — fails before any third-party provider request
+- Occurs only at specific times — it is a first-party-service token-acquisition/refresh failure, typically transient
+- No provider status returned — an IS-side exception, before the connection or provider layer (classify it as such from the code + message; there is no `IsServiceError` field)
+- Maps to the `FailedToGetAccessToken` SRE signal
+
+What can cause it:
+- The platform identity/token service could not issue or refresh the token for the first-party service (transient outage or token-lifecycle window)
+- The first-party service (Orchestrator / Feature Flag service) was briefly unavailable when IS requested the token
+- A platform-side configuration or trust issue between IS and the first-party service
+
+> **This is NOT a connection-credential problem.** The customer's connection OAuth token is unrelated to `DAP-GE-3004`. If the symptom is a genuine connection whose third-party OAuth token expired or was revoked, that surfaces as a provider `401` ([request-failed.md](./request-failed.md)) or the Maestro-surfaced [connection-auth-expired.md](./connection-auth-expired.md) — re-authenticate the connection there, not here.
+
+What to look for:
+- **No `ConnectionId` tied to a failing third-party auth** — the failure is platform-internal, not connection-scoped
+- Whether the failure is intermittent / clustered in time (points to a transient first-party-service token window) vs sustained (points to a platform fault)
+- Whether other tenants/processes hit the same code in the same window (a platform-wide signal, not a single workflow)
+
+## Investigation
+
+1. **Confirm it is the first-party-service token path, not a connection.** No third-party `ProviderErrorCode` / provider status (the failure is inside IS, not a provider response). Do **not** chase the connection — a healthy `uip is connections ping` here does not rule the cause out, and an unhealthy one is a separate issue.
+2. **Establish timing and blast radius.** Check whether `DAP-GE-3004` is intermittent and whether it correlates with a known Orchestrator / Feature Flag service disruption window in the triage evidence.
+3. **Check for recurrence.** A single occurrence that does not repeat on retry is a transient first-party-service token blip. Repeated/sustained occurrences indicate a platform fault to escalate.
+
+## Resolution
+
+**Primary: retry, then escalate — do NOT re-authenticate the connection.** The token comes from a first-party service, not the customer's connection.
+
+- **Transient (single / intermittent):** re-run the job. First-party-service token acquisition usually recovers on its own; the run should succeed on retry.
+- **Sustained / repeated:** escalate to the Integration Service owner team with the `DAP-GE-3004` code, `RequestId`, timestamps, and the affected first-party service (Orchestrator / Feature Flag service). This is a platform token-acquisition fault the customer cannot resolve from their workflow.
+- **Do not** attempt connection re-authentication, connection editing, or connector auth-config changes for this code — they do not address a first-party-service token failure.