@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/job-faulted-logon-failure.md

@@ -0,0 +1,103 @@
+---
+confidence: medium
+---
+
+# Could Not Start Executor — Logon Failed for User
+
+## Context
+
+An unattended job faults immediately (typically < 2 seconds) because the Robot could not establish a Windows session on the target machine for the configured user. The Robot service is up and the machine is reachable, but the user credential it tried to use was refused by Windows.
+
+What this looks like:
+- Job state: Faulted, near-zero runtime (StartTime ≈ EndTime, often < 1 s)
+- Error contains one or more of: `Could not start executor`, `Logon failed for user <DOMAIN>\<USER>`, `RDP connection failed`, Windows codes like `0x0000052E` (logon failure), `0x00000775` (account locked out), `0x00000532` (password expired), `Last error: 131092`
+- May be intermittent (some jobs on the same machine succeed) or persistent (every job on that machine/user fails)
+
+What can cause it (cause-branches — pick the right one from evidence):
+
+1. **Session configuration mismatch** — Process has `requiresUserInteraction: true` (needs a desktop session), but no user is logged in AND "Login to Console" is false. The Robot has no session to attach to and no permission to create one.
+2. **Account locked in Active Directory** — Repeated bad logons (often from a stale credential — see branch 3) or an admin lockout tripped AD's lockout policy. Windows refuses every logon until the account is unlocked.
+3. **Password mismatch (stale credential in Orchestrator)** — User's AD password was rotated, but the credential stored in Orchestrator (Tenant → Credential Stores / robot user) still holds the old one. Each job attempt logs on with the wrong password.
+4. **Lockout loop (chained 3 → 2)** — Branch 3 driving branch 2: Orchestrator keeps trying the stale password, each retry counts as a failed logon, and after N attempts the account locks. Unlocking without first fixing the stored password just re-locks on the next job.
+5. **MFA / Conditional Access enforced on the service account** — A tenant policy added Multi-Factor Authentication or a Conditional Access rule to the user. Unattended Robots cannot satisfy an interactive MFA challenge, so Windows / Entra rejects the logon.
+6. **RDP slot already taken by another user** — Windows Server (non-Terminal-Services) typically allows only one or two concurrent RDP sessions. Another human user (admin, ops, the service-account holder themselves) is logged in via RDP, leaving no slot for the Robot to create a session. Also occurs when a previous RDP session was disconnected without logoff and is still holding the slot.
+
+What to look for:
+- **Pattern:** intermittent vs. persistent across recent jobs on the same machine/user
+- **Same-user / different-machine:** does the same robot user fail on another machine? (Yes → credential/account problem. No → machine/RDP problem.)
+- **Same-machine / different-user:** does a different robot user succeed on the same machine? (Yes → user-specific, not machine. No → machine/session problem.)
+- **Lockout pattern:** rapid repeat-failures (every few minutes) followed by an even harder block → branch 4 fingerprint
+- **Recent AD password rotation** on this user (ask the user; check AD `PasswordLastSet`) → branch 3 / 4
+- **Recent MFA / Conditional Access policy rollout** in the tenant → branch 5
+- **Whose session is on the machine** — `query session` / `quser` on the host shows any active or disconnected RDP session that may be holding a slot → branch 6
+
+## Investigation
+
+Go in this order — cheaper checks first, and each step narrows the branch.
+
+1. **Get the faulted job:** `uip or jobs get <job-key> --output json`. Capture `MachineName`, `RobotName` / user, `StartTime`, `EndTime`, `Info` / error message. Look at the exact wording — `Logon failed`, `account is locked`, `password has expired`, `RDP connection failed`, and any `0x000005..` / `131092` codes are the strongest single hint about the branch.
+2. **Recent-jobs history on the same machine:**
+   `uip or jobs list --folder-path '<folder>' --limit 20 --output json`
+   - Mixed success/failure on the same machine/user → branches 1 or 6 (session/RDP availability) more likely than 2/3/5.
+   - Every recent job on this user has faulted with the same logon error → branches 2, 3, 4, or 5 (user-side problem).
+   - Other users succeed on the same machine → rules out a pure machine/network cause.
+3. **Check `requiresUserInteraction`** (Orchestrator UI → Processes → process → Settings → "Requires User Interaction"). Not exposed via `uip` CLI.
+4. **If `requiresUserInteraction: true`** — check "Login to Console":
+   - `uip or users get <user-key> --output json` and look for `unattendedRobot.executionSettings.LoginToConsole`.
+   - If the field/command isn't available, fall back to UI: Tenant → Users → user → Access Rules → Advanced Robot Options.
+   - **Login to Console = false** → **branch 1** (session-config mismatch). Stop here.
+   - **Login to Console = true** → continue, the Robot is allowed to create its own session, so a logon failure points at the credential or account itself.
+5. **Distinguish branches 2 / 3 / 4 (account + password problems):**
+   - Ask the user (or check AD): when was `PasswordLastSet` for this user? Was it changed recently and **not updated in Orchestrator**? → branch 3.
+   - On a domain controller: `Get-ADUser <user> -Properties LockedOut, badPwdCount, lastBadPasswordAttempt` (or AD Users & Computers → Account tab → "Unlock account" checkbox state). LockedOut = true → branch 2 surface.
+   - `badPwdCount` climbing fast around job-trigger times **plus** LockedOut = true → **branch 4** (lockout loop). This is critical: unlocking without fixing the Orchestrator credential just re-arms the loop.
+   - Have an admin try the stored credential **manually** (log on to the VM with it once). If it fails with "wrong password" → branch 3. If it fails with "account is locked" → branch 2. If it prompts for MFA → branch 5.
+6. **Check for MFA / Conditional Access (branch 5):**
+   - Entra/Azure AD admin center → Users → service account → Authentication methods, and Conditional Access → Policies → filter by this user/group.
+   - Robot/Windows logs typically show an interactive-auth requirement that the unattended logon could not satisfy.
+7. **Check RDP slot (branch 6):**
+   - On the host: `query session` or `quser` (run as admin) — list all sessions including Active and Disconnected.
+   - In Orchestrator, only one Active RDP session is generally available for an unattended Robot. A disconnected-but-not-logged-off session still holds the slot.
+   - Cross-check the job's `MachineName` and `StartTime` against who was on the host at that moment.
+
+## Resolution
+
+Map the branch identified in Investigation to the fix:
+
+- **Branch 1 — Session configuration mismatch:**
+  - Option A: Set "Login to Console" to true on the robot user (Orchestrator → Tenant → Users → user → Access Rules → Advanced Robot Options), so the Robot creates its own console session when no one is logged in.
+  - Option B: Ensure a user is logged into the machine before jobs run.
+  - Prevention: For processes with `requiresUserInteraction: true`, default Login to Console to true.
+- **Branch 2 — Account locked:**
+  - Have a domain admin unlock the account in Active Directory (AD Users & Computers → user → Account → "Unlock account", or `Unlock-ADAccount -Identity <user>`).
+  - **Do not unlock blindly** — first confirm whether branch 3 / 4 is driving the lockout (next bullet), or you'll re-lock immediately.
+- **Branch 3 — Password mismatch:**
+  - Update the password stored in Orchestrator to match the current AD password. Location depends on how the robot user is set up:
+    - Tenant Users: Tenant → Users → user → Robot password
+    - Folder-scoped robot account: edit the robot's credential
+    - Credential Store: edit the asset that holds the password
+  - Then have an admin unlock the AD account (branch 2 fix) so the next job can attempt with the correct password.
+  - Verify by **manually logging on** to the VM with the new credential before re-triggering.
+- **Branch 4 — Lockout loop (always treat as a sequence):**
+  1. Disable triggers / pause the schedule for this process and any others using the same robot user.
+  2. Update the password in Orchestrator (branch 3 fix).
+  3. Unlock the AD account (branch 2 fix).
+  4. Manually verify the credential by logging into the VM once.
+  5. Re-enable triggers.
+  - Prevention: rotate AD passwords for robot service accounts in lockstep with Orchestrator. If feasible, exempt the service account from interactive password expiry (with compensating controls), or use a non-expiring managed service account / gMSA-style pattern.
+- **Branch 5 — MFA / Conditional Access:**
+  - Exclude the service account from MFA and from interactive-auth-requiring Conditional Access policies. In Entra: Conditional Access → policy → Users → Exclude → add the service account or a "Service Accounts" group.
+  - If org policy forbids MFA exclusion, move the workload to a non-interactive auth model (e.g., Modern Folders with a registered application using app-only auth, where supported), or to UiPath Cloud Robots which sidestep the interactive Windows logon entirely.
+  - Prevention: keep robot service accounts in a dedicated group with a documented MFA/CA exemption.
+- **Branch 6 — RDP slot conflict:**
+  - On the host (as admin): `logoff <session-id>` for the disconnected session that's holding the slot, or have the current user disconnect properly.
+  - For ongoing risk: enable "Login to Console" so the Robot uses the console session instead of competing for RDP slots; or upgrade the host to Windows Server with the Remote Desktop Session Host role and a Remote Desktop CAL pool sized for concurrent sessions.
+  - Prevention: dedicate the unattended host to the Robot — humans should not RDP into it during business hours, or should always log off (not disconnect) after admin work.
+
+## Prevention (cross-branch)
+
+- Use a dedicated service account per environment for unattended Robots; don't share with admin users.
+- Rotate the service-account password in Orchestrator **at the same time** as in AD (or just before, then unlock).
+- Exempt service accounts from MFA / interactive Conditional Access policies via a documented group.
+- Default `Login to Console = true` for unattended robot users whose processes require user interaction.
+- Monitor `badPwdCount` and account-lockout events for robot service accounts; alert on the climbing pattern that precedes branch 4.

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/job-pending-no-host.md

@@ -0,0 +1,42 @@
+---
+confidence: high
+---
+
+# Job Pending — No Available Host
+
+## Context
+
+What this looks like:
+- Job stuck in Pending state
+- Job information shows "No host is available on the machine template assigned for this job"
+- Output shows "The job hasn't finished yet"
+- The machine template assigned to the job currently has zero connected runtimes (`robotVersions` empty / no signed-in Assistant)
+
+What can cause it:
+- Host machine's UiPath Assistant is not signed in to Orchestrator
+- UiPath Assistant is connected to a different Orchestrator URL or tenant than the one where the job was triggered
+- UiPath Robot Service is stopped on the host machine
+- Network connectivity lost between host and Orchestrator
+
+What to look for:
+- Machine template assigned to the job and which hosts are registered to it
+- Connection status of hosts on that machine template (connected vs disconnected)
+
+**Discriminator vs [job-pending-stale-dispatch.md](./job-pending-stale-dispatch.md):** before concluding no-host, check `uip or machines list --all-fields` for the assigned template. If it currently has a connected runtime (`robotVersions` populated) AND credentials/mode are valid AND `JobHistory` contains only the original Pending entry, the host is actually present — the `PendingReasons.Errors` codes are a stale snapshot from the original dispatch attempt. Switch to that playbook; the remediation is to stop and re-trigger, not to provision a host. Two traps that look like no-host but are not: the PendingReasons phrase "…none connected to **this folder**" is the dispatch-time verdict, NOT current proof the template is unassigned (no `uip` command can verify folder→template assignment, so do not confirm that as a cause); and `Used.Unattended == Allowed` is NOT exhaustion when the consumed slot is the connected template's own idle runtime.
+
+## Investigation
+
+1. Check the machine template assigned to the pending job and its connected hosts — `uip or machines list --output json`
+2. Check the local machine's hostname and compare it against the hosts registered to the machine template to determine if the agent is running on one of the assigned machines
+3. If on the assigned machine: check the Robot Service status — `sc query UiRobotSvc`
+4. Check whether the Assistant process is running — `tasklist /FI "IMAGENAME eq UiPath.Assistant.exe"`
+5. If the service is running, verify the Assistant is connected to the same Orchestrator URL and tenant where the job is pending
+6. If NOT on the assigned machine: the job is targeting a different machine — the user needs access to that machine or the job needs to be reassigned
+
+## Resolution
+
+- **If on the assigned machine and Assistant is signed out:** sign in to the Assistant and connect to the Orchestrator URL
+- **If on the assigned machine and Assistant is connected to the wrong Orchestrator/tenant:** update the connection in Assistant preferences to point to the correct Orchestrator URL and tenant
+- **If on the assigned machine and Robot Service is stopped:** restart the UiPath Robot Service
+- **If on the assigned machine and network issue:** verify the host can reach the Orchestrator URL, check firewall/proxy settings
+- **If not on the assigned machine:** either connect to the assigned machine and restore Assistant connectivity, or reassign the job to a machine template that includes the current machine

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/job-pending-stale-dispatch.md

@@ -0,0 +1,63 @@
+---
+confidence: high
+---
+
+# Job Pending — Stale Dispatch-Time PendingReasons
+
+## Context
+
+A job is stuck in `Pending` state with `PendingReasons.Errors` codes that no longer describe the current state. Orchestrator captured these reasons at dispatch time and does NOT re-evaluate them while the job remains Pending — even when the underlying conditions have since been resolved.
+
+What this looks like:
+- Job `state = Pending`, no state transitions in `JobHistory`
+- `PendingReasons.Errors` includes one or more of: `TemplateNoHostsAvailable`, `DynamicJobConnectedMachinesInvalid`, `DynamicJobConnectedMachinesWindowsRobotVersionInvalid`
+- BUT the machine template assigned to the job currently reports a connected runtime (`robotVersions` populated)
+- AND the robot account has a Windows credential configured
+- AND the Assistant on the host is in Machine Key / Service Mode (Unattended)
+- AND an Unattended runtime is licensed and idle — the template's own connected runtime holds the slot, so `Used.Unattended == Allowed` is the *healthy* reading here, NOT exhaustion (see Investigation step 3)
+- AND `JobHistory` contains only the single original Pending entry — no later events
+
+The contradiction between the stale error codes and the now-eligible runtime is the signature. The job is technically dispatchable right now; Orchestrator just hasn't re-checked since the initial dispatch failed.
+
+What can cause it:
+- At dispatch time no Unattended runtime was connected, or the connected runtime didn't have a Windows credential, or the license slot was occupied, etc. — any of the `job-pending-no-host` causes could have produced the original PendingReasons.
+- Since dispatch, the underlying issue was fixed (runtime reconnected, credential added, license freed), but the job was never stopped + re-triggered, so Orchestrator never re-evaluated.
+
+## Investigation
+
+1. **Read `PendingReasons.Errors`** on the job — `uip or jobs get <job-key> --output json`. Confirm the codes are no-host-family (`TemplateNoHostsAvailable` etc.).
+2. **Read `JobHistory`** for the job — `uip or jobs history <job-key> --output json`. If only the original Pending entry exists with no later events, Orchestrator has not re-evaluated since dispatch.
+3. **Verify each documented cause is currently resolved** so the discriminator vs `job-pending-no-host.md` holds:
+   - Machine template has a connected runtime — `uip or machines list --all-fields` should show `robotVersions` populated on the assigned template.
+   - Robot account has a Windows credential — confirm with the user (or via the robot-account details if available).
+   - Assistant is in Machine Key / Service Mode (Unattended) — confirm with the user.
+   - An Unattended runtime is licensed and free to take the job. `uip or licenses info` reports `Used.Unattended` = the count of **connected/allocated** Unattended runtimes, NOT the count of running jobs. The template's connected idle runtime holds its slot, so `Used == Allowed` is *expected and healthy* when that slot belongs to the assigned template — it is NOT exhaustion. Confirm the runtime is idle rather than busy with a different job: `uip or jobs list --folder-key <key> --state Running --output json`. If no OTHER Unattended job is Running, the licensed runtime is available for this job. Treat the license as the blocker ONLY when a *different* Running Unattended job holds the slot.
+4. **All four prerequisites confirmed AND PendingReasons.Errors unchanged AND JobHistory shows no re-evaluation** → the conclusion is stale-dispatch.
+
+> **Do not invent a folder-assignment cause.** The PendingReasons text "…there is none connected to this folder" is Orchestrator's eligibility verdict **captured at dispatch time** — not live proof that the machine template is unassigned from the folder. No `uip` command enumerates folder→machine-template assignments, so a "template not assigned to the folder" root cause cannot be evidenced and MUST NOT be confirmed (shared.md invariants #1, #9). If `machines list` shows the assigned template currently has a connected runtime AND `JobHistory` has only the original Pending entry, the codes are stale: this playbook applies and the fix is stop + re-trigger — not a folder reconfiguration.
+
+## Resolution
+
+**Stop the Pending job and re-trigger the process.**
+
+- In Orchestrator: Jobs → select the Pending job → Stop / Kill.
+- Re-trigger the process from the same folder. The fresh dispatch performs a new eligibility check against the current state (host connected, credential present, license slot free) and the job should transition to Running.
+- If a re-triggered job is also Pending with the same `ErrorCodes`, the underlying cause was NOT actually resolved — switch to [job-pending-no-host.md](./job-pending-no-host.md) and walk its sub-cause list.
+
+Do NOT attempt to "fix" the stale codes by reassigning the template, adding the template to the folder's machine list, freeing a license, restarting the Robot Service, or signing in to Assistant — those remediations apply to `job-pending-no-host.md`. In this scenario the runtime is already connected and licensed; the only action that matters is forcing Orchestrator to re-evaluate via a new dispatch.
+
+## Discriminator vs job-pending-no-host
+
+| Signal | `job-pending-no-host` | `job-pending-stale-dispatch` |
+|---|---|---|
+| `PendingReasons.Errors` | Host-family codes | Host-family codes |
+| Template has connected runtime (`robotVersions` populated) | No | Yes |
+| Robot account Windows credential present | Maybe | Yes |
+| Assistant in Service Mode | Maybe | Yes |
+| Unattended runtime licensed & idle (`Used == Allowed`, no other Running job) | Maybe | Yes |
+| `JobHistory` past the original entry | Maybe | No (only the original Pending entry) |
+| Remediation | Provision the missing prerequisite | Stop + re-trigger |
+
+Both playbooks can match in triage. Triage records both; the hypothesis tester resolves which one applies by checking the four "currently resolved" signals plus `JobHistory` shape. If all four are resolved AND `JobHistory` is unchanged, this playbook wins.
+
+> Common misreads that wrongly eliminate this playbook: (1) reading `Used.Unattended == Allowed` as license exhaustion when the slot is held by the assigned template's own idle runtime; (2) reading "none connected to this folder" as a current folder-assignment gap. Both are addressed above — neither moves the verdict toward `job-pending-no-host` when a connected runtime is present.

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/job-stuck.md

@@ -0,0 +1,35 @@
+---
+confidence: low
+---
+
+# Job Stuck in Running
+
+## Context
+
+A job remains in Running state indefinitely with no progress visible in traces.
+
+What this looks like:
+- Job shows Running state for an unusually long time
+- No progress visible in job traces
+- Robot may still appear as Busy
+
+What can cause it:
+- Robot service not running or unresponsive on the host machine
+- Process waiting for user input (attended) with no visible Assistant dialog
+- BPMN/Agentic Process (ProcessOrchestration runtime) — these have different stuck patterns than standard jobs
+- For ProcessOrchestration jobs: the job may be serverless (no robot/machine). If HostMachineName is empty, heartbeat detection and robot-level timeouts don't apply
+- Debug run with redirected folder bindings changing execution context
+- Child service task stuck waiting for completion
+
+What to look for:
+- Check job traces for the last activity that executed
+- Check if the process is ProcessOrchestration runtime — look for empty HostMachineName
+- Check if there's a ParentJobKey — if so, query the parent job's state
+- Check if a child service task is stuck
+
+## Resolution
+
+- If robot is unresponsive: restart the UiPath Robot Service
+- If attended and waiting for input: check the Assistant dialog visibility
+- If ProcessOrchestration with stuck child task: investigate the child task
+- If debug run: check for debug_overwrites.json in the source project

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/queue-items-failing.md

@@ -0,0 +1,38 @@
+---
+confidence: medium
+---
+
+# Queue Items Failing
+
+## Context
+
+Queue items are transitioning to Failed status. Multiple distinct error types may be present across items. Successful items may still be processing normally.
+
+What can cause it:
+- Input data issues — failed items have different SpecificContent from successful ones
+- Failures clustering around a specific time window or machine
+- Performer process was recently updated and introduced a regression
+- Asset, permission, or configuration issue affecting only certain data paths
+
+What to look for:
+- Compare input data (SpecificContent) between failed and successful items to identify data-driven failures
+- Check if failures cluster around a specific time window or machine
+- Check if the performer process was recently updated
+
+## Investigation
+
+1. Get ALL failed queue items (paginate if >100) — do NOT stop at the first page
+2. Categorize failures by error type — there may be MULTIPLE distinct failure modes
+3. After identifying a failure mode, count how many items it explains. If the count does not match the total number of failed items, there are additional failure modes — keep investigating until every failed item is accounted for
+4. Get 2-3 successful queue items for comparison
+5. Compare input data between failed and successful items
+
+A confirmed hypothesis is only a complete root cause if it accounts for ALL failed items. If it explains only a subset (e.g., 156 of 160), the remaining items have a different root cause — classify the finding as partial and continue investigating.
+
+When source code is available, trace the full execution path for EACH error category, not just the first one found. Different queue item data can trigger different code paths and different failures.
+
+## Resolution
+
+- Fix input data at source (dispatcher process or upstream system)
+- Fix the performer process if a regression was introduced
+- Restore asset/permission/configuration if that was the cause

package/skills/uipath-troubleshoot/references/products/orchestrator/playbooks/robot-credentials.md

@@ -0,0 +1,43 @@
+---
+confidence: high
+---
+
+# Robot Credentials or Machine User Mismatch
+
+## Context
+
+What this looks like:
+- Job faults with "The unattended robot has the wrong machine credentials to execute the job (the username of the machine is not the same as the username in the user credentials)"
+- Job stuck in Pending with PendingReason `RobotNoMatchingUsernames` — the robot user account does not match any machine user mapping
+- Job stuck in Pending with PendingReason `TemplateNoLicense` — the machine template has zero Unattended runtime slots allocated
+
+All three are manifestations of the same category: the folder's robot/machine configuration cannot execute unattended jobs.
+
+What can cause it:
+- No robot user account assigned to the folder
+- Robot user account credentials do not match the machine's configured username
+- Machine template has zero Unattended runtime slots (`UnattendedSlots: 0`)
+- Unattended runtime licenses exhausted at the tenant level
+
+What to look for:
+- The exact error message or PendingReason from the job
+- Whether the folder has robot users assigned
+- Whether the machine template has Unattended slots allocated
+
+## Investigation
+
+1. Identify which variant from the job's error message / PendingReason in triage evidence. For the credential variant, confirm from the job details: compare `OrchestratorUserIdentity` (the assigned robot account) against the host machine's configured user — `LocalSystemAccount` and `HostMachineName`. A mismatch between the assigned robot identity and the machine user is the confirmation. The job also has no `StartTime` and a single Pending `JobHistory` entry — the fault is at dispatch, before any robot session started.
+
+   > **`RobotNoMatchingUsernames` interpretation.** The code only fires when Orchestrator IS comparing an assigned robot account against machine users — so the cause is **credential-mismatch** (the robot's credential-store username does not match the machine user), NOT "no robot assigned to the folder". There is no documented `uip` CLI command to list a folder's assigned robot accounts, so the "no robot account assigned" sub-cause cannot be confirmed or ruled out via CLI — record it under `open_gaps`, never report it as the confirmed cause. Do NOT treat an empty `[]` from any exploratory command as proof of absence; absence is contradicted by the error code itself.
+
+2. `uip or machines list --output json` — check if any machine has `UnattendedSlots > 0`. Use `--scope` to filter by scope (Default, Serverless, AutomationCloudRobot, ElasticRobot)
+3. `uip or licenses info --output json` — check available Unattended runtime count at the tenant level. **For `RobotNoMatchingUsernames` specifically, license is NOT the bottleneck** — Orchestrator emits a dedicated license-family code (e.g., `TemplateNoLicense`) when licenses are actually exhausted, not `RobotNoMatchingUsernames`. `Used.Unattended == Allowed` here is the assigned template's own allocated slot, not exhaustion. Do NOT report license exhaustion as a confirmed cause for this PendingReason
+
+## Resolution
+
+- **If `RobotNoMatchingUsernames` or "wrong machine credentials":** the assigned robot account's stored username does not match the host machine's user. Fix with one of:
+  - **Update the machine credentials** on the account's unattended robot so the stored Windows username matches the machine's logged-in user.
+  - **Manage the folder's assigned accounts** — create a new account or assign the correct account that maps to the machine user.
+  - **Run the job using a different account** whose unattended robot already has matching machine credentials.
+- **If `TemplateNoLicense` / zero Unattended slots:** allocate Unattended runtime slots to the machine template in Orchestrator > Machines
+- **If tenant-level licenses exhausted:** check tenant license allocation and free up or acquire additional Unattended runtime licenses

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

@@ -0,0 +1,9 @@
+# Orchestrator Presentation Rules
+
+- **Jobs** — display as process name + version. Show job key in parentheses only when needed for commands.
+- **Folders** — display name, not folder ID or folder key
+- **Queues** — display name, not queue ID
+- **Machines** — display name, not machine ID
+- **Robots** — display name, not robot ID
+- **Assets** — display name, not asset ID
+- **Settings** — use the UI-facing label (e.g., "Job execution timeout" not `MaxExpectedRunningTimeSeconds`). If no UI label found, describe the setting functionally.

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

@@ -0,0 +1,13 @@
+# Orchestrator Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — data correlation rules and testing prerequisites for Orchestrator investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Robot Credentials / Machine Mismatch | High | "Wrong machine credentials", PendingReason `RobotNoMatchingUsernames`, or `TemplateNoLicense` — robot/machine configuration cannot execute unattended jobs | [robot-credentials.md](./playbooks/robot-credentials.md) |
+| Could Not Start Executor — Logon Failed | Medium | Unattended job faults immediately with `Could not start executor` / `Logon failed for user` / `RDP connection failed` (codes `0x0000052E`, `0x00000775`, `0x00000532`, `131092`). Covers session-config mismatch, AD lockout, password mismatch, lockout loop, MFA/Conditional Access, and RDP slot conflict | [job-faulted-logon-failure.md](./playbooks/job-faulted-logon-failure.md) |
+| Queue Items Failing | Medium | Queue items transitioning to Failed status with various error types | [queue-items-failing.md](./playbooks/queue-items-failing.md) |
+| Job Stuck in Running | Low | Job remains in Running state indefinitely with no progress | [job-stuck.md](./playbooks/job-stuck.md) |
+| Job Pending — No Available Host | High | Job stuck in Pending with "No host is available on the machine template" error AND template has zero connected runtimes | [job-pending-no-host.md](./playbooks/job-pending-no-host.md) |
+| Job Pending — Stale Dispatch-Time PendingReasons | High | Job stuck in Pending with no-host-family `PendingReasons.Errors` BUT a runtime IS connected, credentials/mode/license are valid, and `JobHistory` has only the original entry — Orchestrator never re-evaluated. Fix: stop + re-trigger | [job-pending-stale-dispatch.md](./playbooks/job-pending-stale-dispatch.md) |
+| Foreground Process Already Running | Medium | `InvalidOperationException: A foreground process is already running. Only one foreground process can run at a time.` — Robot rejects concurrent foreground jobs on the same session | [foreground-already-running.md](./playbooks/foreground-already-running.md) |

package/skills/uipath-troubleshoot/references/runtime-exceptions/investigation_guide.md

@@ -0,0 +1,61 @@
+# Runtime Exceptions Investigation Guide
+
+## Scope Check — First Step
+
+Before investigating, verify the exception originates from the user's workflow code, not from an activity package:
+
+1. Read the full stack trace from logs or job traces
+2. Check the top frames — if the faulting method is in a package namespace (`UiPath.UIAutomationNext.*`, `UiPath.Core.Activities.*`, or any third-party assembly), **stop and redirect** to the relevant package's troubleshooting
+3. Only proceed if the exception is in the user's workflow logic: activity DisplayName, workflow `.xaml` file, or user-authored `.cs` code
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Exception type** — the exception in the data is the exact type the user reported (e.g., `NullReferenceException` not `ArgumentNullException`)
+- **Stack trace location** — the faulted activity or line in the stack trace matches the workflow the user is asking about
+- **Workflow file** — if multiple workflows exist in the project, the error originates from the correct one
+- **Timestamp** — log entries or job traces fall within the time window the user described
+- **Input data** — if the error is data-dependent, confirm you're looking at the same transaction/queue item/input that caused the failure
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## Local Log Directory
+
+On Windows, UiPath Robot execution logs are in:
+
+```
+%localappdata%\UiPath\logs\
+```
+
+**Reading local logs:**
+1. Resolve `%localappdata%` to the actual path (typically `C:\Users\{username}\AppData\Local`)
+2. List the files in the logs directory to identify available log files
+3. Select the most recent log file relevant to the reported error — start with today's date. If no log for today exists, ask the user what date the error occurred
+4. Search the selected log file for the exception type (e.g., `NullReferenceException`)
+5. Extract the full stack trace — it spans multiple lines after the exception message
+6. Identify the faulted activity name, workflow file, and source line from the stack trace
+
+## Source Code Analysis
+
+Two source formats exist:
+
+### XAML Workflows (RPA)
+- Activities are XML elements with `DisplayName` attributes
+- Variables are declared in `<Variable>` sections within scope containers
+- Arguments are in `.xaml` file headers or `project.json`
+- Trace the data flow: where does the null variable get assigned? What upstream activity produces it?
+
+### Coded Workflows (C#)
+- Standard C# files in the project directory
+- Stack trace line numbers map directly to source lines
+- Check null-coalescing patterns, nullable types, and guard clauses
+
+## Testing Prerequisites
+
+1. **Full stack trace** — extract from local logs or Orchestrator job traces
+2. **Source code path** — the project directory; required to trace variable assignments and data flow
+3. **Faulted activity/line** — identify the specific activity (XAML) or line (C#) from the stack trace
+4. **Variable origin** — trace backward from the null variable to find where it was supposed to be assigned
+5. **Input data** — check what data the workflow received (arguments, queue item, asset values) for the failing execution
+6. **Conditional paths** — check if the null value comes from a branch that doesn't assign the variable

package/skills/uipath-troubleshoot/references/runtime-exceptions/overview.md

@@ -0,0 +1,35 @@
+# Runtime Exceptions
+
+General .NET runtime exceptions originating from the user's own workflow code — variable handling, data processing, argument passing, and control flow logic.
+
+## Scope Boundary
+
+These playbooks ONLY cover exceptions where the root cause is in the user's workflow code (`.xaml` or `.cs` files they wrote). The user has access to this code and can fix it.
+
+**If the stack trace shows the exception originates inside an activity package** (e.g., `UiPath.UIAutomationNext.Activities`, `UiPath.Core.Activities`, or any third-party package namespace), this is NOT a runtime exception issue — route to the relevant activity package troubleshooting instead. The user cannot fix code inside packages they don't own.
+
+**How to tell:** check the top frames of the stack trace. If the faulting method is in a `UiPath.*` or third-party namespace, it's a package issue. If it's in the user's workflow (activity DisplayName, workflow filename, or user-authored C# code), it belongs here.
+
+## Investigation Sources
+
+### Local Workflow Execution (Studio / Robot)
+
+The user ran the workflow locally. Troubleshooting data comes from:
+- **Execution logs** in `%localappdata%\UiPath\logs\` (Windows) — list files in this directory and select the appropriate log based on date
+- **Source code** — the project directory containing `.xaml`, `.cs`, or `project.json` files
+
+Ask the user for the project location.
+
+### Orchestrator Job Execution
+
+The workflow ran as an Orchestrator job. Troubleshooting data comes from:
+- **Job traces** via `uip or` CLI commands
+- **Job error details** (OutputArguments, Info field)
+- **Source code** — if available, provides the full picture
+
+## Common Exception Types
+
+| Exception | Description |
+|-----------|-------------|
+| `System.NullReferenceException` | Code attempted to use an object reference that is null |
+| `System.ArgumentNullException` | A method received a null argument where non-null was required |

package/skills/uipath-troubleshoot/references/runtime-exceptions/playbooks/argument-null-exception.md

@@ -0,0 +1,47 @@
+---
+confidence: medium
+---
+
+# Argument Null Exception
+
+## Context
+
+`System.ArgumentNullException` ("Value cannot be null") in the user's workflow code. A null value was passed to a method or activity that requires a non-null argument. Unlike `NullReferenceException` (which occurs when you USE a null value), this occurs when you PASS a null value to something that rejects it.
+
+**Scope:** only applies when the exception originates from the user's workflow logic — a null argument passed by the user's code to a method or activity. If the stack trace shows the fault deep inside an activity package namespace with no user code in the call chain, redirect to that package's troubleshooting.
+
+What this looks like:
+- Workflow faults with `System.ArgumentNullException`
+- Error message: "Value cannot be null" typically followed by `(Parameter 'paramName')`
+- May occur intermittently when the null argument depends on input data or configuration
+
+What can cause it:
+- Invoke Workflow File doesn't supply a required In argument (or the mapped variable is null)
+- Config dictionary lookup returns null (key doesn't exist or value is empty)
+- File/folder path variable is null when passed to I/O activities (Read Range, Move File, Path Exists)
+- Activity receives null for a required input property (Type Into with null text, Add Data Row with null array)
+- Collection variable is null when passed to a method expecting non-null (String.Join, LINQ query)
+
+What to look for:
+- The parameter name in the exception message — directly identifies which argument was null
+- The faulted activity or method in the stack trace
+- The source of the null value (variable, config, argument binding)
+
+## Investigation
+
+1. **Get the stack trace** — for local execution, list `%localappdata%\UiPath\logs\` and open the log for today's date (if not found, ask for the error date); for Orchestrator, get job traces. Confirm the fault originates from the user's workflow code
+2. Extract the parameter name from the error message (`Parameter 'paramName'`) — this is the key troubleshooting signal
+3. Locate the faulted activity in source code and match the parameter name to the activity's input properties or the method being called
+4. Trace the argument source: find where the null value originates (variable assignment, activity output, config lookup, argument binding). Check if the assignment is conditional or depends on external data
+5. Check for missing defaults — does the variable have a default value? Is there a fallback for null?
+6. If intermittent: compare input data between successful and failed executions
+
+The root cause is WHY the argument was null, not which parameter rejected it. A confirmed finding must trace back to the missing assignment, empty config key, or unset argument.
+
+## Resolution
+
+- **If missing Invoke Workflow argument:** map the required In argument in the caller; verify the source variable has a value at invocation time
+- **If null config or asset value:** verify the config key exists and has a non-empty value in the current environment; add a fallback or default
+- **If null file path:** verify the path source (config, asset, environment variable) has a value; add validation before the file operation
+- **If null activity input:** add a null check before the activity; handle the upstream source that produced null
+- **If null collection:** initialize the collection before passing it (New List, New Dictionary, empty array)

package/skills/uipath-troubleshoot/references/runtime-exceptions/playbooks/null-reference-exception.md

@@ -0,0 +1,47 @@
+---
+confidence: medium
+---
+
+# Null Reference Exception
+
+## Context
+
+`System.NullReferenceException` ("Object reference not set to an instance of an object") in the user's workflow code. The workflow attempted to access a member on a variable or expression that is `null`.
+
+**Scope:** only applies when the exception originates from the user's workflow logic (activity, variable expression, or user-authored C# code). If the stack trace shows the fault inside an activity package namespace (e.g., `UiPath.UIAutomationNext.*`), redirect to that package's troubleshooting — the user cannot fix package internals.
+
+What this looks like:
+- Workflow faults with `System.NullReferenceException`
+- Error message: "Object reference not set to an instance of an object"
+- May occur intermittently when the null value depends on input data
+
+What can cause it:
+- Variable declared but never assigned (or assigned only in a conditional branch that wasn't taken)
+- Activity output was null and used directly without a null check (e.g., data table lookup with no match, JSON path that doesn't exist, regex with no match)
+- Queue item field missing or null (`TransactionItem.SpecificContent("fieldName")` with wrong field name)
+- External system returned null or empty response (HTTP Request, database query, SOAP call)
+- Collection used before initialization (array, List, DataTable)
+
+What to look for:
+- Full stack trace — confirms the fault is in workflow code, not a package
+- The specific activity or line where the null access occurred
+- The variable or expression that was null
+
+## Investigation
+
+1. **Get the stack trace** — for local execution, list `%localappdata%\UiPath\logs\` and open the log for today's date (if not found, ask for the error date); for Orchestrator, get job traces. Confirm the top stack frames are in the user's workflow, not a package namespace
+2. Locate the faulted activity in source code by `DisplayName` (XAML) or line number (C#)
+3. Identify which variable or expression was null — read the activity's input properties
+4. Trace the variable backward: find every assignment (Assign activities, activity outputs, argument bindings). Check if any assignment is conditional (If/Else, Switch, Flowchart branch) or inside a Try/Catch that swallows errors
+5. If data-dependent: for Orchestrator jobs, compare TransactionItem/SpecificContent between successful and failed runs; for local execution, check what arguments or config values were passed
+6. Verify variable scope — a variable declared in an inner scope is null if accessed from an outer scope (XAML)
+
+The root cause is WHY the variable was null, not which variable was null. A confirmed finding must trace back to the origin of the null value (missing assignment, conditional gap, missing input data, failed upstream activity).
+
+## Resolution
+
+- **If uninitialized variable:** add a default value or ensure all conditional branches assign the variable before it's used
+- **If activity returned null:** add a null check (If/Then) after the activity before using the output; handle the "no data" case explicitly
+- **If queue item field missing:** verify field names match exactly (case-sensitive) between Add Queue Item and Get Transaction Item; add null check before accessing SpecificContent
+- **If external system returned null:** add response validation; handle empty/null responses as an expected case
+- **If collection not initialized:** initialize the collection (New List, Build Data Table) before first use

package/skills/uipath-troubleshoot/references/runtime-exceptions/summary.md

@@ -0,0 +1,8 @@
+# Runtime Exceptions Playbooks
+
+**Investigation guide:** [investigation_guide.md](./investigation_guide.md) — scope check, data correlation rules, local log paths, and source code analysis for runtime exception investigations
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| Null Reference Exception | Medium | `System.NullReferenceException` in workflow code — uninitialized variable, null activity output, missing data, or unguarded conditional path | [null-reference-exception.md](./playbooks/null-reference-exception.md) |
+| Argument Null Exception | Medium | `System.ArgumentNullException` in workflow code — null value passed to activity or method that requires non-null | [argument-null-exception.md](./playbooks/argument-null-exception.md) |