@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/no-suitable-runtime-machine.md

@@ -0,0 +1,45 @@
+---
+confidence: high
+---
+
+# No Machine With Unattended/NonProduction Runtimes (409, #2818)
+
+## Context
+
+What this looks like:
+- HTTP 409 from Orchestrator surfaced by Maestro
+- Error message: `Operation returned invalid status code '409'. Could not find a machine with Unattended or NonProduction runtimes in the current folder`
+- Orchestrator error code `#2818`
+
+What can cause it:
+- Folder has no machine templates with Unattended or NonProduction runtime slots assigned
+- Folder only has Test Runtimes but Maestro defaults to NonProduction runtime type (tracked historically as `MST-6775`)
+- Tenant has no available runtime licenses
+- Machines exist but are all currently busy or disconnected
+
+What to look for:
+- Folder `Machines` tab — what runtime types are assigned
+- Tenant `License Management` — runtime allocation
+- Package requirements in the Maestro process — which runtime type is selected
+
+## Investigation
+
+> Substitute `<type>` with `bpmn`, `flow`, or `case` per the [Maestro investigation guide](../investigation_guide.md) § Determine the Maestro process type.
+
+
+1. Get the incident: `uip maestro <type> instance incidents <instance-id> -f <folder-key> --output json`
+2. List machines in the folder: `uip or machines list --folder-key <folder-key> --output json` — check runtime slot types
+3. Check tenant runtime license allocation: Orchestrator UI → **Tenant > License Management**
+4. Check the Maestro process's package requirements for the configured runtime type
+
+## Resolution
+
+- **If folder has no compatible runtimes:** add a machine template with Unattended or NonProduction slots via **Folder > Machines**
+- **If tenant only has Test Runtimes:** change the Maestro process's package requirements to a runtime type that matches what the tenant has — see [Managing Package Requirements](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/managing-package-requirements#linking-execution-settings)
+- **If no runtime licenses available:** allocate more in Tenant License Management or contact the UiPath account manager
+- **If all machines busy/disconnected:** verify machine connectivity to Orchestrator; reduce concurrent load
+
+## References
+
+- [Forum: Error #2818](https://forum.uipath.com/t/could-not-find-a-machine-with-unattended-or-nonproduction-runtimes-in-the-current-folder-2818/297757)
+- [Docs: Managing Package Requirements](https://docs.uipath.com/orchestrator/automation-cloud/latest/user-guide/managing-package-requirements#linking-execution-settings)

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/personal-automation-quota.md

@@ -0,0 +1,42 @@
+---
+confidence: high
+---
+
+# Personal Automation Quota Exceeded (502)
+
+## Context
+
+What this looks like:
+- HTTP 502 surfaced by Maestro when starting a job
+- Error message: `Automation cannot be started. Your user's monthly Personal Automation quota has been exceeded.`
+- Often reported as Orchestrator error code `170002` propagated through a Maestro service task
+
+What can cause it:
+- User is on a Personal Automation license plan and has consumed the monthly Robot Unit allocation
+- Agentic Unit allocation expired (free trial ended) on the user/tenant
+- Concurrent Personal Automation usage across multiple workspaces
+
+What to look for:
+- Incident `errorMessage` is self-explanatory — quota text appears verbatim
+- Affects only the user/owner of the workspace, not the tenant
+
+## Investigation
+
+> Substitute `<type>` with `bpmn`, `flow`, or `case` per the [Maestro investigation guide](../investigation_guide.md) § Determine the Maestro process type.
+
+
+1. Get the incident: `uip maestro <type> instance incidents <instance-id> -f <folder-key> --output json`
+2. Confirm error text matches the quota wording above. If error code is `170002`, drill into the child Orchestrator job to see the underlying quota response
+3. Check tenant consumption: Orchestrator UI → **Admin > Tenant > Licenses > Consumption**
+4. If the user is running agents, also confirm Agentic Units are available (separate quota)
+
+## Resolution
+
+- **If Personal Automation quota exhausted:** request a license upgrade via [self-service license increase](https://uipath.atlassian.net/wiki/spaces/LIC/pages/2834596253), or wait for the monthly quota reset
+- **If Agentic Units expired:** allocate AU from **Admin > Organization > Subscriptions** or contact the UiPath account manager
+- **If recurring:** redesign the workflow to use a tenant-level Unattended robot instead of Personal Automation so quotas come from the shared pool
+
+## Notes
+
+- This is not a Maestro platform bug. Quota enforcement happens in Orchestrator's job execution layer; Maestro surfaces it as 502
+- The incident `errorMessage` already contains everything needed — no PIMS deep-dive required

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/process-not-found-404.md

@@ -0,0 +1,47 @@
+---
+confidence: high
+---
+
+# Job's Associated Process Not Found (404)
+
+## Context
+
+What this looks like:
+- HTTP 404 from Orchestrator surfaced by Maestro
+- Error message: `Operation returned invalid status code '404'. The job's associated process could not be found`
+- Often reported as Maestro error code `170007` (`OrchestratorRpaJobFailedToStart`) when the failure occurs at job-start time
+
+What can cause it:
+- Stale or incorrect `ReleaseKey` in the service task binding
+- Process was deleted, renamed, or moved to a different folder
+- Solution imported across environments (staging → alpha) where folder keys / release keys were baked in
+- API call missing the `X-UIPATH-OrganizationUnitId` header (folder context)
+- Debug binding override pointing at a folder where the dependency was not deployed (the "Will be deployed in Debug folder" trap)
+
+What to look for:
+- Compare `bindings_v2.json` (deployed) or `debug_overwrites.json` (debug) with the actual processes in the target folder
+- Check whether the solution was re-imported from another environment recently
+
+## Investigation
+
+> Substitute `<type>` with `bpmn`, `flow`, or `case` per the [Maestro investigation guide](../investigation_guide.md) § Determine the Maestro process type.
+
+
+1. Get the incident: `uip maestro <type> instance incidents <instance-id> -f <folder-key> --output json`
+2. Find the failing service task in element executions: `uip maestro <type> instance element-executions <instance-id> -f <folder-key> --output json`
+3. Pull the binding for the failing task — request `bindings_v2.json` (deployed) or `debug_overwrites.json` (debug) from the user
+4. Look up the `ReleaseKey` in Orchestrator: `uip or processes get <release-key> --output json` (process keys are tenant-unique; no folder context needed)
+5. Verify the folder key in the binding matches the folder the instance is actually running in
+
+## Resolution
+
+- **If ReleaseKey is stale or missing:** re-publish the solution against the correct folder; update bindings; re-deploy
+- **If solution was cross-imported:** re-create the folder mapping or re-bind dependencies in the destination environment
+- **If debug mode:** change the debug config from "Will be deployed in Debug folder" to use the already-deployed dependency in the target folder
+- **If API call:** include the `X-UIPATH-OrganizationUnitId` header pointing at the correct folder
+- **If process was moved/renamed:** update the ReleaseKey, robot account, environment, and machine config in the binding
+
+## References
+
+- [Forum: Start job via API in Modern Folders](https://forum.uipath.com/t/start-job-process-via-api-in-modern-folders-the-jobs-associated-process-could-not-be-found/478483)
+- [Forum: StartJobs API error](https://forum.uipath.com/t/startjobs-api-the-jobs-associated-process-could-not-be-found-error/29637)

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/service-task-child-job-faulted.md

@@ -0,0 +1,38 @@
+---
+confidence: high
+---
+
+# Service Task Child Job Faulted (170002)
+
+## Context
+
+What this looks like:
+- Maestro instance stuck in Running state with an open incident
+- Incident error code 170002 — "Failure in the Orchestrator Job"
+- Child job launched by a service task has faulted
+
+What can cause it:
+- The child RPA job or agent faulted (selector failure, application exception, argument mismatch, etc.)
+- The child job was stopped or cancelled externally
+- Robot disconnected mid-execution
+
+What to look for:
+- The child job's error message and final state — the child's failure reason is the actual root cause, not the parent's error code
+- Which service task in the BPMN process triggered the child job
+- Whether the service task has a boundary error event attached
+
+## Investigation
+
+Service tasks are a BPMN concept — use the `bpmn` subcommand. For Flow/Case service-equivalent failures, swap `bpmn` for `flow` or `case`.
+
+1. Get full incident details: `uip maestro bpmn instance incidents <instance-id> -f <folder-key> --output json`
+2. Get element executions to identify the faulted service task: `uip maestro bpmn instance element-executions <instance-id> -f <folder-key> --output json`
+3. Find the child job key from the incident's `errorDetails` and inspect it: `uip or jobs get <child-job-key> --output json` — the child's error message drives the root cause investigation
+4. Get child job logs for execution detail: `uip or jobs logs <child-job-key> --level Error --output json`
+5. Check whether a boundary error event is attached to the service task (visible in element executions)
+
+## Resolution
+
+- **Resolve the open incident** to unblock the BPMN instance — either retry the service task or mark the incident as resolved, depending on process design
+- **Add a boundary error event** to the service task in Studio Web so future child job failures are caught and routed to an error-handling flow (retry, notification, or alternative path) instead of blocking the instance with an unresolved incident
+- **Root cause is in the child domain** — investigate the child job failure separately (selector issue, permission error, etc.)

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/unattended-robot-permissions.md

@@ -0,0 +1,44 @@
+---
+confidence: high
+---
+
+# No Unattended Robot Permissions in Folder (409, #1671)
+
+## Context
+
+What this looks like:
+- HTTP 409 from Orchestrator surfaced by Maestro at job-start time
+- Error message: `Operation returned invalid status code '409'. Couldn't find any user with unattended robot permissions in the current folder.`
+- Orchestrator error code `#1671`
+
+What can cause it:
+- No user with an Unattended Robot license is assigned to the Orchestrator folder where the Maestro service task runs
+- The "Unattended Automations" permission is missing on the folder role even though the license is granted at tenant level
+- Process was built in classic Studio (desktop) where unattended robots are required, but the deployment folder has none — switching to Studio Web (Agentless/Serverless runtime) is a workaround
+- API call missing or pointing the `OrganizationUnitId` header at the wrong folder
+
+What to look for:
+- Incident `folderKey` — tells you exactly which folder to inspect
+- Is the underlying RPA project a Studio (desktop, `.xaml`) or Studio Web project? Studio Web runs on serverless and does not need an unattended robot
+
+## Investigation
+
+> Substitute `<type>` with `bpmn`, `flow`, or `case` per the [Maestro investigation guide](../investigation_guide.md) § Determine the Maestro process type.
+
+
+1. Get the incident: `uip maestro <type> instance incidents <instance-id> -f <folder-key> --output json`
+2. Extract `folderKey` from `errorDetails`
+3. List users assigned to that folder: `uip or users list-in-folder --folder-key <folder-key> --output json`
+4. Inspect license assignments: Orchestrator UI → **Tenant > Manage Access > Users** for the relevant user
+5. Confirm the underlying RPA project type — Studio (desktop) vs Studio Web
+
+## Resolution
+
+- **If user has no Unattended license:** Orchestrator UI → **Tenant > Manage Access > Users** → enable "Unattended Robot" for the user
+- **If permission missing on the folder:** assign the user to the folder with a role that includes "Unattended Automations"
+- **If using a Studio (desktop) project unnecessarily:** rebuild the workflow in Studio Web so it runs on Agentless/Serverless
+- **If API call:** make sure `X-UIPATH-OrganizationUnitId` points at the folder where the unattended user is assigned
+
+## References
+
+- [Forum: Error #1671](https://forum.uipath.com/t/couldnt-find-any-user-with-unattended-robot-permissions-in-the-current-folder-1671/417804)

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/variable-expression-errors.md

@@ -0,0 +1,40 @@
+---
+confidence: medium
+---
+
+# Variable and Expression Errors
+
+## Context
+
+What this looks like:
+- "Missing output variables"
+- "Assignments are not allowed in expressions"
+- "Failed to evaluate the input collection variable"
+- Exclusive gateway conditions not matching expected values
+
+What can cause it:
+- Drag/drop swimlane bug — moving task nodes in swimlanes can clear root-level variable references
+- Variable name case sensitivity in exclusive gateway conditions (e.g., "customer" vs "Customer")
+- Emoji characters in condition expressions causing evaluation failures
+- Salesforce Execute Connector SOQL "=" operator falsely flagged as assignment (fixed in later releases)
+- Sub-process variable propagation — error detail and category fields may not propagate to parent process (known limitation, check latest release notes)
+
+What to look for:
+- Check which expression or variable is failing
+- Check if task nodes were recently moved between swimlanes
+- Check for case mismatches in gateway conditions
+
+## Investigation
+
+1. Identify the exact error message and which variable/expression is affected
+2. Check if the variable exists at the root level of the BPMN process
+3. For gateway conditions: compare variable names case-sensitively against the condition expression
+4. Check for special characters (emoji, unicode) in expressions
+5. For sub-process variables: check if error detail/category fields are expected in the parent process
+
+## Resolution
+
+- **If missing variable references:** re-create the output variable references on the affected task node
+- **If case mismatch:** fix the variable name or condition expression to match exactly
+- **If emoji/special characters:** remove special characters from expressions
+- **If SOQL assignment error:** update to the latest version or rewrite the filter expression

package/skills/uipath-troubleshoot/references/products/maestro/presentation.md

@@ -0,0 +1,8 @@
+# Maestro Presentation Rules
+
+- **Instances** — display as BPMN process name (instance ID in parentheses only when needed for commands)
+- **Incidents** — display as error code + error message. When referencing an incident by ID, use the `incidentId` field (not `id`). The API returns both: `id` is the record's internal GUID, `incidentId` is the user-facing identifier (same as `elementRunId`) shown in Maestro Instance Management.
+- **Solutions** — display name, not solution key
+- **Service tasks** — use the task name from the BPMN process, not the internal element ID (e.g., "Send Email task" not "Activity_EW6HNH")
+- **Settings** — use UI labels from Maestro Instance Management, not API property names
+- **Error codes** — always include both the numeric code and the human-readable message (e.g., "170002 — Failure in the Orchestrator Job")

package/skills/uipath-troubleshoot/references/products/maestro/summary.md

@@ -0,0 +1,56 @@
+# Maestro Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Maestro investigations
+
+**Top-20 production errors (telemetry-ranked, last 7 days as of 2026-03-19):** the table below covers the highest-volume Maestro errors first, with a generic table after for additional symptoms. Source: [PO.BpmnEngine PR #3092](https://github.com/UiPath/PO.BpmnEngine/pull/3092).
+
+## Top 20 Production Errors
+
+| # | Error | Status | Error Code | Playbook |
+|---|-------|:------:|------------|----------|
+| 1 | Personal Automation quota exceeded | 502 | — | [personal-automation-quota.md](./playbooks/personal-automation-quota.md) |
+| 2 | Job's associated process could not be found | 404 | 170007 | [process-not-found-404.md](./playbooks/process-not-found-404.md) |
+| 3 | No unattended robot permissions in folder | 409 | #1671 | [unattended-robot-permissions.md](./playbooks/unattended-robot-permissions.md) |
+| 4 | Job Operation Timeout | 502 | — | [job-operation-timeout.md](./playbooks/job-operation-timeout.md) |
+| 5 | Input does not conform to schema | 400 | — | [input-schema-mismatch.md](./playbooks/input-schema-mismatch.md) |
+| 6 | Missing value for required parameter | 400 | — | [missing-required-parameter.md](./playbooks/missing-required-parameter.md) |
+| 7 | Generic Error_400 | 400 | — | [generic-error-400.md](./playbooks/generic-error-400.md) |
+| 8 | Expression evaluation — property not found | 400 | 400300–400302 | [expression-evaluation-errors.md](./playbooks/expression-evaluation-errors.md) |
+| 9 | No outgoing flow condition met | 400 | 400001 | [gateway-no-outgoing-flow.md](./playbooks/gateway-no-outgoing-flow.md) |
+| 10 | Loop detected (>100 executions) | 400 | 400009 | [loop-detected.md](./playbooks/loop-detected.md) |
+| 11 | 'File' field required (DAP-RT-1003) | 502 | DAP-RT-1003 | [file-field-required.md](./playbooks/file-field-required.md) |
+| 12 | Integration Services 404 | 404 | 102001 | [integration-service-404.md](./playbooks/integration-service-404.md) |
+| 13 | Insufficient funds / credits | 400 | — | [insufficient-funds.md](./playbooks/insufficient-funds.md) |
+| 14 | Marker element input collection is null | 400 | 400007 | [marker-input-null.md](./playbooks/marker-input-null.md) |
+| 15 | Integration Services 400 | 400 | 102003 | [integration-service-400.md](./playbooks/integration-service-400.md) |
+| 16 | Folder does not exist or no access | 400 | #1100 | [folder-not-accessible.md](./playbooks/folder-not-accessible.md) |
+| 17 | No machine with Unattended/NonProduction runtimes | 409 | #2818 | [no-suitable-runtime-machine.md](./playbooks/no-suitable-runtime-machine.md) |
+| 18 | No Message events found | 400 | — | [no-message-events.md](./playbooks/no-message-events.md) |
+| 19 | Foreground job requires unattended robot | 409 | #1230 | [foreground-unattended-robot.md](./playbooks/foreground-unattended-robot.md) |
+| 20 | Index outside bounds of array | 502 | — | [index-out-of-bounds.md](./playbooks/index-out-of-bounds.md) |
+
+> **API debuggability:** errors #1, #3, #5, #6, #8, #11, #13, #16, #19 are **Fully Troubleshootable** from PIMS API alone. Errors #2, #4, #10, #14, #17 are **Partially Troubleshootable** — incident gives a starting point but needs Orchestrator or BPMN inspection. Errors #7, #9, #12, #15, #18, #20 are **Not Troubleshootable** from API alone today; ask the user for additional artifacts (`.bpmn`, bindings, full stack trace).
+>
+> Error #9 (`NoOutgoingFlow`) becomes Fully Troubleshootable once [PR #3092](https://github.com/UiPath/PO.BpmnEngine/pull/3092) lands and the `IncludeGatewayDebugInfoInIncidents` targeted feature flag is enabled.
+
+## Additional Symptoms (Lower Volume)
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Maestro Service Disabled | High | Designer pane blank or errors after license change — service silently disabled | [maestro-service-disabled.md](./playbooks/maestro-service-disabled.md) |
+| Deployment Error — EMAIL_RECEIVED | High | Error code 4006, IS/packaging sync issue with Outlook email trigger | [deployment-email-received.md](./playbooks/deployment-email-received.md) |
+| Deployment Error — DateTime Input | High | "Package entry points definition is invalid" due to DateTime BPMN input parameters | [deployment-datetime-input.md](./playbooks/deployment-datetime-input.md) |
+| JS Runtime Discrepancy | High | JS expression passes in editor but fails at runtime — Jint lacks browser APIs | [js-runtime-discrepancy.md](./playbooks/js-runtime-discrepancy.md) |
+| Agent Traces Disappearing | High | Traces missing due to AI Trust Layer Trace TTL policy | [agent-traces-disappearing.md](./playbooks/agent-traces-disappearing.md) |
+| Autopilot 429 Too Many Requests | High | HTTP 429 rate limiting on Autopilot features | [autopilot-429.md](./playbooks/autopilot-429.md) |
+| Multi-Instance Marker InvalidCastException | High | JS array cannot be cast to ExpressionList — switch to C# expressions | [marker-invalid-cast.md](./playbooks/marker-invalid-cast.md) |
+| Attachment Not Found After Retention | High | Files disappear when job retention deletes the owning job | [attachment-not-found.md](./playbooks/attachment-not-found.md) |
+| Argument Mismatch (400) — Generic | Medium | Generic 400 argument mismatch; route to #5 or #6 for specifics | [argument-mismatch-400.md](./playbooks/argument-mismatch-400.md) |
+| Service Task Child Job Faulted (170002) | High | Error 170002, child job faulted — chase child error as root cause, add boundary error event | [service-task-child-job-faulted.md](./playbooks/service-task-child-job-faulted.md) |
+| Debug vs Deploy Mismatch | Medium | Process works in debug but fails after deploy — identity, permissions, or bindings | [debug-vs-deploy.md](./playbooks/debug-vs-deploy.md) |
+| Deployment Failure | Medium | Solution deployment fails — duplicate entry points, trigger conflicts, or stale references | [deployment-failure.md](./playbooks/deployment-failure.md) |
+| Variable and Expression Errors | Medium | Missing output variables, assignment errors, case sensitivity in gateway conditions | [variable-expression-errors.md](./playbooks/variable-expression-errors.md) |
+| Boundary Event / Duplicate Task | Medium | Task running twice, boundary events firing unexpectedly, missing incident logging | [boundary-event-duplicate-task.md](./playbooks/boundary-event-duplicate-task.md) |
+| File Handling Issues | Medium | Files not passed correctly, attachment not found, file type incompatibility | [file-handling.md](./playbooks/file-handling.md) |
+| Multi-Instance Parallel Marker | Medium | Parallel marker failures, collection size limits, NoneType errors | [multi-instance-parallel.md](./playbooks/multi-instance-parallel.md) |
+| BPMN Job Stuck | Low | Instance stuck with no progress or error — disconnected connection, child job not created, or backend delay | [bpmn-job-stuck.md](./playbooks/bpmn-job-stuck.md) |

package/skills/uipath-troubleshoot/references/products/orchestrator/investigation_guide.md

@@ -0,0 +1,73 @@
+# Orchestrator Investigation Guide
+
+## Data Correlation
+
+Before fetching ANY job, queue, or asset data, resolve identity first:
+
+1. **Folder** — resolve the folder key (GUID). All Orchestrator data is folder-scoped. Use `uip or folders list` to find all accessible folders (Personal, Solution, and Standard) — the default view is scoped to the current user. Use `uip or folders list --all` only when you need every folder in the tenant (filtering and sorting flags require `--all`). Use `uip or folders get <key-or-path>` to confirm details. If the folder is inaccessible, STOP — nothing else will be valid without it. **After resolving the folder, verify it contains the target entity** (e.g., run `uip or jobs get <key>` or a scoped query for the expected process/queue). If the target entity is not found in the resolved folder, try other folders from `folders list` before continuing. Do NOT proceed with a folder that returns empty results for the target entity.
+2. **Process** — identify the process name (from user input, working directory `project.json`, or package name). All subsequent queries filter by this process.
+3. **Time window** — establish the relevant period from the user's report.
+
+Only after identity is resolved, fetch data and verify every result against it:
+
+- **Process/Release** — job release name matches the identified process
+- **Queue** — queue name matches what the user reported (if queue-related)
+- **Robot/Machine** — if the user mentioned a specific robot or machine, verify the data belongs to it
+- **Timestamps** — fall within the established time window
+
+If data doesn't match: **discard it**. Do NOT fetch details for jobs or items from other processes. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+4. **Job selection** — if multiple jobs exist for the identified process, present the list to the user (showing state, timestamp, error summary) and ask which one to investigate. If the user said "latest" or didn't specify, default to the most recent faulted job and state this assumption explicitly. Do NOT fetch details for multiple jobs — investigate one at a time. **If the user gave no job key but described the job by state + folder** (e.g. "my pending job in Shared"), resolve it by enumeration: `uip or jobs list --folder-key <key> --state <State> --output json`. If exactly one candidate matches, proceed with it; if several, present them and ask. Do not ask the user for a key you can discover this way.
+5. **Queue item** — if the issue is queue-related, resolve the queue and item. Use `uip resource queues list --folder-key <key> --name <name>` to find the queue definition key. If the user provided a queue item key, use `uip resource queue-items get <item-key> --folder-key <key>` to confirm it exists and extract the queue name, error details, and retry status. If the queue item is not found in the first folder, try other folders from `folders list`.
+
+## Job Data Bundle
+
+For every job under investigation, gather these in order. Write each to `raw/` immediately.
+
+1. **Job details** — `uip or jobs get <key>` — state, input/output arguments, timing, machine info, error details
+2. **Job logs** — `uip or jobs logs <key>` — robot execution logs, newest-first. Folder is inferred from the job key. Use `--level Error` to quickly find errors. Use `--limit` to control how many entries (default 50)
+3. **Job history** — `uip or jobs history <key>` — job state transition history (timestamps for each state change: Pending → Running → Faulted). Useful for identifying delays and lifecycle issues.
+4. **Job traces** — `uip or jobs traces <key>` — job execution traces (activity states, variable snapshots, execution path). Available for all job types.
+
+This is the baseline. Domain-specific data gathering builds on it — see the investigation guide for each matched domain (UI Automation, Integration Service, Maestro) for additional steps after the baseline.
+
+## Queue Item Data Bundle
+
+For every queue item under investigation, gather these in order. Write each to `raw/` immediately.
+
+1. **Resolve queue** — `uip resource queues list --folder-key <key> --name <name>` — find the queue definition and its key
+2. **Queue item details** — `uip resource queue-items get <item-key> --folder-key <key>` — status, SpecificContent, processingException, retry count
+3. **Queue item history** — `uip resource queue-items get-history <item-key> --folder-key <key>` — state transitions with timestamps (New → InProgress → Failed/Retried)
+4. **Last retry** — `uip resource queue-items get-last-retry <item-key> --folder-key <key>` — details of the most recent retry attempt
+
+For comparison investigations (e.g., queue-items-failing playbook), also gather successful items:
+
+5. **List failed items** — `uip resource queue-items list --queue-definition-key <queue-key> --folder-key <key> --status Failed` — all failed items for comparison
+6. **List successful items** — `uip resource queue-items list --queue-definition-key <queue-key> --folder-key <key> --status Successful --limit 3` — sample of successful items to compare SpecificContent
+
+## Finding Related Jobs
+
+When investigating service tasks, child jobs, or multi-job processes, use `jobs list` to find related jobs:
+
+```
+uip or jobs list --folder-key <folder-key> --process-name <name> --created-after <start> --created-before <end> --output json
+```
+
+Key flags (all optional, but `--folder-key` or `--folder-path` is required):
+- `--folder-key <key>` — folder GUID (required, or use `--folder-path`)
+- `--state <state>` — filter by state: Pending, Running, Successful, Faulted, Stopped, Stopping, Suspended, Resumed, Terminating
+- `--process-name <name>` — filter by process name (contains match)
+- `--created-after <datetime>` / `--created-before <datetime>` — narrow to a time window (ISO 8601)
+
+Use this to find child jobs spawned by Maestro service tasks, or to identify other faulted jobs for the same process around the same time.
+
+## Testing Prerequisites
+
+When testing hypotheses for Orchestrator issues, gather and verify these before drawing conclusions:
+
+1. **Folder context** — confirm the folder the process runs in; permissions, jobs and assets are folder-scoped
+2. **Process version** — confirm the deployed package version matches what the user expects
+3. **Robot assignment** — verify the robot/machine template is assigned to the folder and has capacity
+4. **Execution logs** — use job traces/logs to reconstruct the actual execution path, don't infer from job status alone
+5. **Timing** — check job start/end times, queue transaction durations, and trigger schedules against reported symptoms
+6. **Dependencies** — check `## Dependencies` in `overview.md` for cross-product issues (e.g., Identity Server, Elasticsearch, SQL Server)

package/skills/uipath-troubleshoot/references/products/orchestrator/overview.md

@@ -0,0 +1,83 @@
+# Orchestrator
+
+Web application that manages automation resources, robots, processes, and execution. Central hub for attended and unattended automation orchestration.
+
+Orchestrator serves as the backbone for:
+- **Deployment** — publishing automation packages and managing versions
+- **Execution** — starting, stopping, and monitoring automation jobs
+- **Configuration** — managing assets, queues, and environment settings
+- **Scheduling** — defining triggers and schedules for unattended execution
+- **Monitoring** — tracking job status, execution logs, and system health
+
+## Organization Model
+
+```
+Organization (cloud.uipath.com)
+  └── Tenant                        ← Isolated environment (dev, staging, prod)
+        └── Folder                  ← Logical container for resources
+              ├── Processes         ← Published .nupkg automation packages
+              ├── Jobs              ← Running or completed executions
+              ├── Assets            ← Key-value configuration store
+              ├── Queues            ← Distributed work item queues
+              ├── Triggers          ← Event/queue-based job triggers
+              ├── Schedules         ← Cron-based job scheduling
+              ├── Storage Buckets   ← File storage for automation data
+              ├── Machines          ← Robot execution environments
+              └── Robots            ← Attended/Unattended agents
+```
+
+## Dependencies
+
+- **Identity Server** — authentication and token management; Orchestrator cannot function without it
+- **SQL Server** — stores all Orchestrator data (jobs, queues, assets, audit, configuration)
+- **Elasticsearch** (optional) — stores robot execution logs; if unavailable, logs are lost but jobs still run
+- **IIS / ASP.NET Core** — hosts the Orchestrator web application
+- **Load Balancer / Reverse Proxy** — in clustered deployments, routes traffic and terminates SSL
+
+## Features
+
+- **Robot Management** — Provisioning, configuration, and monitoring of attended and unattended robots
+- **Process Execution & Job Management** — Launch and monitor automation jobs with dynamic robot dispatch
+- **Queues & Transaction Management** — Work item queue management with priority, state tracking, retries
+- **Queue Triggers** — Auto-launch jobs when queue items arrive
+- **Scheduled Triggers** — Time-based recurring triggers for unattended execution
+- **Folders & Tenants** — Hierarchical org modeling with resource isolation
+- **Assets** — Key-value config store (text, int, bool, credential, secret)
+- **Machine Management** — Machine objects for robot host tracking
+- **Packages Management** — NuGet package repository for automation packages
+- **Storage Buckets** — Folder-scoped file storage (Azure, S3, MinIO, FileSystem)
+- **Credential Stores** — Pluggable credential providers (Azure Key Vault, HashiCorp)
+- **Webhooks** — Event subscriptions with HTTP delivery and HMAC signing
+- **OData REST API** — Programmatic API for all Orchestrator entities
+- **Role-Based Access Control** — Fine-grained RBAC with default and custom roles
+- **Monitoring** — Real-time dashboards for machines, queues, processes (30-day window)
+- **Alerts** — In-app notifications, email summaries, custom Raise Alert activity
+- **Logs** — Robot execution log capture per folder
+- **Audit** — Audit trail of administrative actions for compliance
+
+## CLI
+
+```
+uip or folders list                                 — list all accessible folders (Personal, Solution, Standard). Add --all for every folder in the tenant.
+uip or folders get <key-or-path>                    — get folder details
+uip or jobs list --folder-key <key>                 — list jobs in a folder. Filters: --state, --process-name, --created-after/before, --started-after/before
+uip or jobs get <key>                               — job details: state, arguments, timing, machine, errors
+uip or jobs logs <key>                              — robot execution logs (--level Error, --limit N). Folder inferred from key.
+uip traces spans get --job-key <key>                — job execution traces (activity states, execution path)
+uip traces spans get <trace_id>                     — job execution traces based on the 'jobInformation.TraceId' field
+uip or jobs history <key>                           — job state transition history (Pending → Running → Faulted, with timestamps)
+uip or machines list                                — list registered machines
+uip or licenses info                                — license allocation and usage
+```
+
+Key commands for troubleshooting:
+- `uip or folders list` — resolve folder key first; default output includes Personal, Solution, and Standard folders the current user can access. Use `--all` only when you need every folder in the tenant.
+- `uip or jobs list --folder-key <key> --state Faulted` — find faulted jobs in a folder. Use `--process-name`, `--created-after/before` to narrow results
+- `uip or jobs get <key>` — starting point for any job investigation
+- `uip or jobs logs <key> --level Error` — quickly find error entries in execution logs
+- `uip traces spans get --job-key <key>` — job execution traces (activity states, execution path)
+- `uip traces spans get <trace_id>` — job execution traces based on the 'jobInformation.TraceId' field
+- `uip or jobs history <key>` — job state transition history with timestamps
+
+Queue and queue-item commands are documented in the investigation guide's Queue Item Data Bundle section.
+

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/foreground-already-running.md

@@ -0,0 +1,65 @@
+---
+confidence: medium
+---
+
+# Foreground Process Already Running — InvalidOperationException
+
+## Context
+
+A job fails to start (or terminates immediately) because the Robot refuses to run two foreground (UI-interactive) processes at the same time on the same Windows session. Only one foreground job per session is permitted; additional background jobs may run in parallel.
+
+What this looks like:
+- Error message: `System.InvalidOperationException: A foreground process is already running. Only one foreground process can run at a time.`
+- Job state: Faulted with near-zero runtime, or never transitions from Pending → Running on the target machine
+- Visible in UiPath Robot logs (`%LocalAppData%\UiPath\Logs\Execution.log`) and surfaced in Orchestrator job details
+- May appear in Assistant when manually starting a process
+
+What can cause it:
+- **Attended Robot conflict** — user starts two processes simultaneously via UiPath Assistant
+- **Foreground vs. background misconfiguration** — a non-UI process is built/published as foreground when it doesn't need UI interaction, so it competes for the foreground slot unnecessarily
+- **Orchestrator queue overload** — multiple foreground jobs triggered for the same user/Robot at the same time
+- Two foreground triggers fire on overlapping schedules against the same Robot/session
+- Manual start (Assistant or Orchestrator "Start Job") while a previously scheduled foreground job is still running
+- Orchestrator retry policy launches a new attempt before the previous one has fully exited
+- **Remote machine session disconnected or minimized** — RDP session was disconnected without logoff; foreground state on the host is inconsistent and the slot appears taken
+- Orphaned `UiPath.Executor.exe` or `UiRobot.exe` from a prior run still holds the foreground slot (often after an abnormal session termination — see related `STATUS_CONTROL_C_EXIT` / RDP-drop scenarios)
+- Concurrent attended + unattended execution on the same logged-in user session
+
+What to look for:
+- Recent job history on the same machine — was another foreground job Running or only recently Completed/Faulted?
+- `Process.IsForeground = true` on both the running and the failing process definitions
+- A stuck `UiPath.Executor.exe` in Task Manager after the prior job's StartTime, with no corresponding running job in Orchestrator
+- Trigger schedules that fire close together (e.g., every 5 min on a 7-min process)
+
+## Investigation
+
+1. Get the failing job: `uip or jobs get <job-key> --output json`. Note `MachineName`, `StartTime`, `EndTime`, and `RobotName`.
+2. List recent jobs on the same machine to find an overlapping foreground job:
+   `uip or jobs list --folder-path '<folder>' --limit 20 --output json`. Look for any Running job, or a Completed/Faulted job whose `EndTime` is at or after the failing job's `StartTime`.
+3. Confirm both processes are foreground:
+   - Orchestrator UI → Processes → select process → Settings → check "Background Process" is **off** (or `requiresUserInteraction: true`).
+4. Check for orphaned executor processes on the host:
+   - `Get-Process UiPath.Executor, UiRobot -ErrorAction SilentlyContinue | Format-Table Id, ProcessName, StartTime, SessionId`
+   - Cross-reference SessionId with the user that should own the job. An executor running with no matching Orchestrator job is orphaned.
+5. Review Robot logs near the failure timestamp: `%LocalAppData%\UiPath\Logs\Execution.log` for prior session terminations (RDP disconnect, session logoff, `0x40010004` exits) that could have left the slot locked.
+6. Review trigger configuration: Orchestrator → Triggers — look for cron expressions that can overlap given the typical job duration.
+
+## Resolution
+
+- **Attended Robot conflict (two processes started from Assistant):** stop one of the running processes from the Assistant, then re-trigger sequentially. Educate users that the Assistant cannot run two foreground processes concurrently.
+- **Process does not actually need UI interaction:** convert it to a background process at the **source** (Studio → Project Settings → set `"Starts in Background"` to **Yes** in `project.json`, then republish), or at the deployment level (Orchestrator → Process → Settings → "Background Process" = true). Background jobs do not consume the foreground slot.
+- **Legitimate concurrent foreground jobs needed:** sequence the triggers so they cannot overlap (stagger cron expressions, chain via Maestro/parent process), or enable **"Run only one job at a time"** on the Robot in Orchestrator (Tenant → Robots → edit → Execution Settings) so subsequent jobs queue instead of failing.
+- **Orchestrator queue overload:** for the same user, configure jobs to run sequentially or split the load across multiple Robots/machine templates.
+- **Orphaned `UiPath.Executor.exe` / `UiRobot.exe` holding the slot:**
+  - Verify it is not bound to an active Orchestrator job before killing.
+  - `Stop-Process -Id <pid> -Force` for the orphan, or restart the Robot service: `Restart-Service UiPath.Robot` (run as admin).
+  - Investigate **why** it was orphaned (session was killed externally — RDP drop, logoff, machine restart). Repeated orphaning points at session-stability issues, not at this exception.
+- **Remote machine session disconnected or minimized:** keep the RDP session alive (do not "X" out — use Disconnect carefully or keep the session active via a console session / kiosk lock), and use `Activate` activities in the workflow so the target window is brought to the foreground reliably. For unattended scenarios, configure "Login to Console" so the Robot can manage its own console session instead of relying on an interactive RDP.
+- **Orchestrator retry policy firing too aggressively:** increase the retry delay on the process, or set max retries to 0 and handle failures via a parent workflow that waits for clean state.
+- **Attended + unattended collide on the same user session:** isolate attended runs to the user's interactive workflow only and route unattended runs to a separate Robot/machine template.
+
+Prevention:
+- Keep at most one foreground process scheduled per Robot session, or enable "Run only one job at a time" on the Robot.
+- Default new automations to background (`"Starts in Background": true` in `project.json`) unless they truly require UI interaction.
+- For high-throughput scenarios, use multiple Robots or convert UI-less steps to background processes.
+- Ensure session terminations clean up — see related session-stability investigation when the orphan pattern repeats.