@uipath/skills 1.195.0

package/skills/uipath-troubleshoot/references/products/llm-gateway/playbooks/validation-probe-failed.md

@@ -0,0 +1,54 @@
+---
+confidence: medium
+---
+
+# BYO LLM Validation Probe Failing
+
+## Context
+
+What this looks like:
+- `uip llm-configuration byo-connections create` or `update` exits non-zero with `Result: Failure`
+- The error references the validation probe: `isAvailable: false`, `isCompatible: false`, or `isModelNameSimilar: false` for one or more models
+- The save was aborted (server-side validation is mandatory; there is no skip flag)
+
+What can cause it:
+- The vendor key behind the IS connection does not have access to the requested model (subscription / region / deployment mismatch)
+- The chosen `--api-flavor` is not supported by the model — e.g., a Bedrock-only model with `OpenAiResponses`
+- The product's allowed-model catalog (`models[]` or `addYourOwn[<connector-type>]`) changed since the config was created and the saved `--llm-name` is no longer valid against preflight rules
+- `--llm-identifier` (the value sent to the vendor) does not match the deployment name / inference profile ID the vendor expects — e.g., Azure OpenAI deployment names, AWS Bedrock region-prefixed inference profiles (`eu.anthropic.claude-...`)
+- The IS connection itself is dead (route to [byo-connection-dead.md](./byo-connection-dead.md) first if the probe error mentions auth)
+
+What to look for:
+- Which model in the probe summary failed (multi-mapping configs return one verdict per model)
+- The `Message` and `Instructions` fields on the error envelope
+- Whether the failure is `isAvailable` (vendor access / key scope), `isCompatible` (model × api-flavor mismatch), or `isModelNameSimilar: false` (typo / deprecated model name)
+
+## Investigation
+
+1. **Pin down the failure mode.** Read the validation block in the error payload. Note which model and which probe field failed.
+
+2. **Confirm the catalog still allows the chosen (model, connector, api-flavor) combination:**
+
+   ```bash
+   uip llm-configuration byo-connections list-product-configs \
+     --product <product> --feature <feature> --output json
+   ```
+
+   For `AnyModelWithOwnAdditions` features, check `addYourOwn[<connector-type>]` for the list of allowed api-flavors when adding a custom model.
+   For `AllModels` / `AnyModel` features, check the catalog `models[]` for `allowedApiFlavors` and `allowedConnectors` per model.
+
+3. **If `isAvailable: false`** — the vendor key cannot reach the model. Verify with the vendor (does the API key have access to this deployment / model / region?). If the vendor key was recently rotated, check the IS connection state via `uip llm-configuration byo-connections get <id> --force-refresh`.
+
+4. **If `isCompatible: false`** — the (model, api-flavor) pair is not allowed. Pick a different api-flavor from the catalog probe data.
+
+5. **If `isModelNameSimilar: false`** — `--llm-name` is not a recognized model. Either the customer is on `AnyModelWithOwnAdditions` and the catalog needs widening, or the name is a typo / deprecated variant. Cross-check against `models[]` in the catalog response.
+
+6. **If `--llm-identifier` differs from `--llm-name`** — confirm the deployment name / inference profile ID the vendor expects matches what was passed. Ask the user explicitly.
+
+## Resolution
+
+- For vendor-side access issues — fix the key scope with the vendor, then re-run `create` / `update` with the same flags. Validation will re-probe.
+- For catalog drift — pick a model from the current `list-product-configs` response and re-issue the `create` / `update` with the new value. For multi-mapping (`AllModels` / `AnyModel`), every catalog model must be supplied in the call.
+- For api-flavor mismatch — re-issue with an api-flavor present in the model's `allowedApiFlavors` (or `addYourOwn[<connector-type>]` for `AnyModelWithOwnAdditions`).
+- For `--llm-identifier` mismatch — re-issue with the vendor's deployment name / inference profile ID, leaving `--llm-name` as the catalog name.
+- There is no skip flag — every save must pass validation. If the customer needs a workaround, route to the BYO config description in [`uipath-platform`](/uipath:uipath-platform).

package/skills/uipath-troubleshoot/references/products/llm-gateway/summary.md

@@ -0,0 +1,9 @@
+# LLM Gateway Playbooks
+
+**Overview:** [overview.md](./overview.md) — service model, dependencies, CLI surface, and what the CLI does **not** expose.
+
+| Issue | Confidence | Description | Playbook |
+|-------|:---:|-------------|----------|
+| BYO LLM Call Failing (underlying IS connection dead) | High | Agent / product LLM call used to work and now fails with auth / provider errors — the IS connection behind the BYO config has been revoked, disabled, or had credentials rotated | [byo-connection-dead.md](./playbooks/byo-connection-dead.md) |
+| BYO LLM Validation Probe Failing | Medium | `create` / `update` aborts with `isAvailable: false` or `isCompatible: false` — the model is not reachable through the chosen vendor key + api-flavor, or the catalog drifted since the config was created | [validation-probe-failed.md](./playbooks/validation-probe-failed.md) |
+| BYO LLM Routing Bypassed (call hit platform default) | Medium | Trace spans show the platform default model / provider was used despite an active BYO config — the record is disabled, the feature requires multi-mapping and some models were unmapped, or AI Trust Layer policy overrode the routing | [byo-routing-bypassed.md](./playbooks/byo-routing-bypassed.md) |

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

@@ -0,0 +1,341 @@
+# Maestro Error Codes
+
+Source: `UiPath.PO.Errors/ErrorCode.cs` + `ErrorCodeMessages.resx`
+
+For high-volume production errors, see the **Top-20 Production Errors** table at the bottom of this file. It links engine codes (and Orchestrator codes for non-engine surfaces) to ranked playbooks.
+
+## Error Code Ranges
+
+| Range | Subsystem |
+|-------|-----------|
+| 100000–100052 | Temporal & Instance Service |
+| 100101–100119 | BPMN Package Download & Assets |
+| 101000–101004 | Element Service |
+| 102000–102018 | Integration Service |
+| 103000–103002 | Incident Service |
+| 104000–104067 | Instance DB (Cosmos & SQL) |
+| 105000–105101 | Incident DB (Cosmos & SQL) |
+| 106000–106026 | Process DB & Element Execution DB |
+| 107000–107004 | TraceView Service |
+| 108000–108102 | Insights & Instance Globals |
+| 150001–150009 | Auth & Header Errors |
+| 150100–150110 | GWS (Data Move) |
+| 150200–150203 | Blob Storage |
+| 160000–160012 | Cloud Events |
+| 170000–170041 | Orchestrator Runtime (OR) |
+| 180000–180003 | Studio Web (SW) |
+| 190001 | Timer |
+| 200000–200103 | Activity & Observability |
+| 200200–200201 | Hermes |
+| 300000–300010 | BPMN Engine |
+| 300100–300103 | Data Pipe |
+| 300200–300208 | Data Fabric |
+| 300300–300301 | VDO |
+| 300400–300403 | Business Rules |
+| 300450–300461 | Case Management |
+| 300500–300503 | Script Tasks |
+| 300600–300604 | HTTP Request Tasks |
+| 400000–400023 | BPMN Elements |
+| 400050–400051 | Case Select Next Stage |
+| 400100–400110 | Instance Operations |
+| 400200–400404 | PTS & Process Service |
+| 400300–400302 | Expression Evaluation |
+| 400500–400505 | Licensing |
+| 400600–400601 | Optimize |
+| 400700 | PIMS Middleware |
+| 400800–400805 | Admin |
+| 400900–400908 | Tenant Metadata |
+| 400911–400923 | Overwatch |
+| 410000–410202 | DynamicExpresso & Variable Storage |
+| 420000 | Call Activity |
+| 430000–430002 | IXP (Document Understanding) |
+| 440000–440002 | Signal Events & Instance Globals |
+| 450002–450013 | Message Events |
+
+## Temporal & Instance Service (100000–100052)
+
+| Code | Name | Message |
+|------|------|---------|
+| 100000 | InstancesServiceTemporalClient | Error creating temporal client |
+| 100001 | TemporalFacadeCreateConflict | Instance already exists in storage |
+| 100002 | InstancesServiceDuplicateRequest | Duplicate request to Instances service |
+| 100003 | TemporalFacadeCreateException | Error creating instance |
+| 100004 | TemporalFacadeResetException | Error resetting workflow |
+| 100005 | TemporalClientFacadeFetchHistoryException | Error fetching history |
+| 100006 | TemporalFacadePauseException | Error pausing workflow |
+| 100007 | TemporalFacadeCompleteSuspendedActivityException | Error completing suspended activity |
+| 100008 | TemporalFacadeResumeException | Error resuming workflow |
+| 100009 | InstancesServicePausingStatusChangeFailed | Pausing status change failed |
+| 100010 | InstancesServiceResumingStatusChangeFailed | Resuming status change failed |
+| 100011 | InstancesServiceRetryStatusChangeFailed | Retry status change failed |
+| 100012 | TemporalFacadeRetryException | Error retrying execution |
+| 100013 | TemporalFacadeDebugCreateConflict | Debug instance creation conflict |
+| 100014 | TemporalFacadeDebugCreateException | Debug instance creation error |
+| 100015 | TemporalFacadeBreakpointException | Error setting breakpoint |
+| 100016 | TemporalFacadeReopenCaseException | Failed to reopen case instance |
+| 100017 | TemporalFacadeContinueOnBreakpointException | Error continuing on breakpoint |
+| 100018 | VariablesProcessorInvalidJsonPatch | Invalid JSON patch for variables |
+| 100019 | CosmosInstanceConflictException | Instance already exists in storage |
+| 100020 | TemporalFacadeCancelException | Error canceling workflow |
+| 100021 | InstancesServiceUpgradingStatusChangeFailed | Upgrading status change failed |
+| 100022 | TemporalFacadeUpgradeException | Error upgrading workflow |
+| 100023 | TemporalUpdateVariablesException | Error updating variables |
+| 100024 | UpdatingInstanceVersionFailed | Failed to update the instance package |
+| 100025 | InstanceInvalidPackageKey | Invalid package key format |
+| 100026 | TemporalFacadeVariablesException | Error getting variables |
+| 100027 | InstVarServiceParseBpmnXml | Error parsing BPMN XML for variables |
+| 100028 | VariableEndpointQueryParamInvalid | Invalid query parameter for variables endpoint |
+| 100029 | InstancesServiceGetInstanceRunNotFound | Instance run not found |
+| 100030 | InstancesServiceGetInstanceRunMultipleRuns | Instance has multiple runs (not allowed) |
+| 100031 | InstancesServiceGetInstancesSummaryFailed | Error getting instances summary |
+| 100032 | TemporalFacadeCompleteSuspendedActivityRpcException | Error completing suspended activity (RPC) |
+| 100033 | TemporalFacadeVariablesUnableToFetch | Unable to fetch variables |
+| 100034 | InstanceStatusInvalid | Invalid instance status |
+| 100035 | TemporalActivityAlreadyCompletedException | The Temporal activity is already completed and cannot be completed again |
+| 100036 | TemporalActivityNotFoundToCompleteException | The Temporal activity is not found to complete the activity |
+| 100037 | TemporalFacadeApplyGoToTransitionsException | Error applying GoTo transitions |
+| 100038 | TemporalFacadeGetGoToCursorsException | Error getting GoTo cursors |
+| 100039 | TemporalFacadeCancelRpcException | Error canceling workflow (RPC) |
+| 100040 | TemporalFacadeElementActivationException | Error activating element |
+| 100041 | TemporalFacadePauseElementActivationException | Error pausing element activation |
+| 100042 | TemporalWorkflowNotFound | Workflow not found |
+| 100043 | TemporalFacadeContinueOnBreakpointCompletedException | Breakpoint continuation completed |
+| 100044 | TemporalFacadeCancelElementException | Error while canceling element in Temporal |
+| 100045 | TemporalFacadeRetryElementException | Failed to retry element in the instance |
+| 100046 | ReopenCaseNotCaseManagementInstance | Instance is not a case management process and cannot be reopened |
+| 100047 | ReopenCaseInstanceNotCompleted | Case instance must be in Completed status before it can be reopened |
+| 100048 | InstancesGetAllInvalidPageSize | pageSize must be less than or equal to 500 |
+| 100049 | InstancesGetAllMissingPackageId | packageId filter must be provided along with packageVersion |
+| 100050 | InstancesGetAllInvalidDateRange | startedTimeUtcStart must be before or equal to startedTimeUtcEnd |
+| 100051 | InstancesGetAllInvalidStatus | One or more provided status values are invalid |
+| 100052 | InstancesGetAllInvalidSortField | Invalid sortBy value |
+
+## BPMN Package Download & Assets (100101–100119)
+
+| Code | Name | Message |
+|------|------|---------|
+| 100101 | InstancesServiceBpmnDownloadHttpException | HTTP error downloading BPMN package |
+| 100102 | InstancesServiceBpmnDownloadException | Error downloading BPMN package |
+| 100103 | InstancesServiceBpmnDownloadFailed | BPMN download failed |
+| 100104 | InstancesServiceBpmnDownloadInvalidArgument | Invalid argument for BPMN download |
+| 100105 | DebugBpmnDownloadHttpException | Failed to get the debug package |
+| 100106 | DebugBpmnDownloadException | Failed to get the debug package |
+| 100107 | BpmnServiceNotPde | BPMN service not PDE |
+| 100108 | DebugBpmnFileNotFound | Unable to find file in nuget for debug |
+| 100109 | InstancesServiceBpmnFileNotFound | Unable to find BPMN file in package |
+| 100110 | InstancesServiceFileNotFound | Unable to find file in package |
+| 100111 | DebugFileNotFound | Unable to find file in debug package |
+| 100113 | DebugPackageDownloadHttpException | Failed to get the debug package |
+| 100114 | DebugPackageDownloadException | Failed to get the debug package |
+| 100115 | AssetNotFound | Asset not found for the specified process |
+| 100116 | AssetDownloadFailed | Failed to download asset from package |
+| 100117 | ProcessReleaseNotFound | No release found for the specified process key and version |
+| 100118 | AssetInvalidType | Invalid asset type. Valid values are: bpmn, case, flow |
+| 100119 | ReleasesApiError | Failed to query releases from Orchestrator |
+
+## Integration Service (102000–102018)
+
+| Code | Name | Message |
+|------|------|---------|
+| 102000 | IntSvcResultNull | Integration Services unexpected empty result |
+| 102001 | IntSvcResourceNotFound | Integration Services resource not found |
+| 102002 | IntSvcOperationFailed | Integration Services operation failed |
+| 102003 | IntSvcBadRequest | Integration Services bad request |
+| 102004 | IntSvcMethodNotSupported | Integration Services method not supported |
+| 102005 | CreateTriggerInvalidInputError | Integration Services invalid input on create trigger operation |
+| 102006 | DeleteTriggerInvalidInputError | Integration Services invalid input on delete trigger operation |
+| 102007 | GetEventPayloadInvalidInputError | Integration Services invalid input on get payload operation |
+| 102008 | GetConnectionInvalidInputError | Integration Services invalid input on get connection operation |
+| 102009 | SendIntSvcTaskInvalidInputError | Integration Services invalid input on send task operation |
+| 102010 | IntSvcArgumentsError | Integration Services invalid value in input |
+| 102011 | DeleteTriggerFailed | Integration Services delete trigger failed |
+| 102012 | LatestRunIdNotFound | Latest run ID not found |
+| 102013 | ExternalAgentApiArgumentsError | External Agent API invalid value in input |
+| 102014 | FileRefRequiredToDataFabric | File reference required to host a file in Data Fabric |
+| 102015 | IntSvcListElementsFailed | Integration Services failed on listing elements operation |
+| 102016 | DebugTriggerEventNoDataError | Trigger activity could not find any matches |
+| 102017 | IntSvcUnifiedHttpRequestInvalidInputError | Invalid input on Unified HttpRequest operation |
+| 102018 | IntSvcUnifiedHttpRequestArgumentsError | Invalid value in Unified HttpRequest input |
+
+## Orchestrator Runtime (170000–170041)
+
+| Code | Name | Message |
+|------|------|---------|
+| 170000 | HitlTaskOperationFailed | Failure in the AppTasks request |
+| 170001 | HitlTaskResultByIdFailed | Failure mapping the data from the task result |
+| 170002 | OrchestratorJobFailed | Failure in the Orchestrator Job |
+| 170003 | PoRuntimeOperationFailed | Failure in the PO runtime operation |
+| 170004 | HitlTaskInputInvalid | Invalid input for the HITL task |
+| 170005 | OrchestratorRpaTaskInputInvalid | Invalid input arguments for the Orchestrator RPA task |
+| 170006 | OrchestratorRpaFailed | Failure in the Orchestrator RPA job |
+| 170007 | OrchestratorRpaJobFailedToStart | Failure to start the Orchestrator RPA job |
+| 170008 | ExecuteWorkflowApiInputError | Invalid input for the ExecuteWorkflowApi activity |
+| 170009 | ApiWorkflowExecutionArgumentsError | Invalid value in input for Api Workflow Execution |
+| 170010 | OrchestratorQueueArgumentsError | Invalid arguments for Orchestrator queue-items |
+| 170011 | OrchestratorQueueItemNotInExpectedState | Orchestrator queue-item is not in expected state, yet |
+| 170012 | OrchestratorQueueItemFailed | Orchestrator queue-item is in Failed state |
+| 170013 | OrchestratorJobDeserializeError | Failure in deserializing Orchestrator Job response |
+| 170014 | HiltTaskAppsFetchFailed | HITL task apps fetch failed |
+| 170015 | HitlTaskNoAppsFoundForGivenInput | No apps found for given input |
+| 170016 | JobAttachmentDownloadError | Error downloading job attachment from Orchestrator |
+| 170030 | OrchestratorApiServerlessJobFailed | Failed to invoke serverless job via Orchestrator API |
+| 170031 | OrchestratorApiFolderLookupFailed | Failed to retrieve folders from Orchestrator API |
+| 170032 | UnknownJobAttachmentRefError | Unknown job attachment reference |
+| 170033 | InvalidJobAttachmentRefError | Invalid job attachment reference |
+| 170034 | OrchestratorGetMachineClientIdError | Failure to start the Orchestrator RPA job |
+| 170035 | OrchestratorServerlessJobFailed | Failure to start the Orchestrator RPA job |
+| 170036 | OrchestratorGetRetentionPeriodError | Failed to retrieve retention period from Orchestrator |
+| 170037 | HitlAppTaskDetailsFetchFailed | Failure to fetch actionable app task details |
+| 170038 | OrchestratorQueueItemCreateFailed | Failed to create queue-item in Orchestrator |
+| 170039 | OrchestratorQueueItemFetchFailed | Failed to fetch queue-item |
+| 170040 | OrchestratorQueueItemDeleted | Queue item is in deleted state |
+| 170041 | OrchestratorGetReleasesBindingsFailed | Failed to fetch bindings from Orchestrator for release |
+
+## BPMN Engine (300000–300010)
+
+| Code | Name | Message |
+|------|------|---------|
+| 300000 | UnsupportedExtensionType | Unsupported extension type |
+| 300001 | InvalidOrCorruptedBpmnModel | Invalid or corrupted BPMN model |
+| 300002 | PatchGlobalVariablesFailure | Error patching global variables |
+| 300003 | PatchElementInputsFailure | Error patching inputs |
+| 300004 | EngineMetadataDeserializationError | Error deserializing engine result metadata |
+| 300005 | FaultedElementThrewNonProblemDetailsException | Unexpected error thrown by BPMN element |
+| 300006 | GoToTransitionSourceNotFound | Source in GoTo transition not found |
+| 300007 | GoToTransitionTargetNotFound | Target in GoTo transition not found |
+| 300008 | GoToTransitionTargetTypeNotSupported | Target type in GoTo transition not supported |
+| 300009 | GoToTransitionSubprocessElementsNotSupported | Transitions involving subprocess elements are not supported |
+| 300010 | UserDefined | User Defined Error |
+
+## Data Fabric (300200–300208)
+
+| Code | Name | Message |
+|------|------|---------|
+| 300200 | DataFabricOperationError | Error in a Data Fabric operation |
+| 300201 | DataFabricUploadFileError | Error uploading file to Data Fabric |
+| 300202 | DataFabricDownloadFileError | Error downloading file from Data Fabric |
+| 300203 | DataFabricReadRecordError | Error reading record from Data Fabric |
+| 300204 | DataFabricInsertRecordError | Error inserting record in Data Fabric |
+| 300205 | DataFabricQueryExpansionError | Error executing query expansion in Data Fabric |
+| 300206 | DataFabricQueryExpansionInvalidFilterError | Invalid filter expression for Data Fabric query expansion |
+| 300207 | DataFabricQueryExpansionNoResultsError | No results found for Data Fabric query expansion |
+| 300208 | DataFabricUpdateRecordError | Error updating record in Data Fabric |
+
+## Business Rules (300400–300403)
+
+| Code | Name | Message |
+|------|------|---------|
+| 300400 | BusinessRulesTaskArgumentsError | Invalid business rule task arguments |
+| 300401 | BusinessRulesGetRuleFailed | Error getting business rule |
+| 300402 | BusinessRulesDownloadRuleFailed | Error downloading business rule |
+| 300403 | BusinessRulesParseRuleFailed | Error parsing business rule |
+
+## Script Tasks (300500–300503)
+
+| Code | Name | Message |
+|------|------|---------|
+| 300500 | ScriptTaskArgumentsError | Invalid script task arguments |
+| 300501 | ScriptTaskInvocationError | Error invoking script task |
+| 300502 | ScriptTaskInvocationResultError | Error obtaining valid script task result |
+| 300503 | ScriptTaskInternalInvocationError | Internal script task invocation error |
+
+## HTTP Request Tasks (300600–300604)
+
+| Code | Name | Message |
+|------|------|---------|
+| 300600 | HttpRequestArgumentsError | Invalid HTTP request arguments |
+| 300601 | HttpRequestExecutionError | Error executing HTTP request |
+| 300602 | HttpRequestTimeoutError | HTTP request timed out |
+| 300603 | HttpRequestInvalidResponseError | Invalid HTTP response received |
+| 300604 | HttpRequestUnexpectedError | Unexpected error occurred during HTTP request |
+
+## BPMN Elements (400000–400023)
+
+| Code | Name | Message |
+|------|------|---------|
+| 400000 | ErrorEndEvent | User defined error for BPMN end event |
+| 400001 | NoOutgoingFlow | No condition for an outgoing flow was met. At least one outgoing flow condition needs to evaluate to true or have a default flow. |
+| 400002 | ElementExecution | Failed to Execute Bpmn Element |
+| 400003 | FailedToParseXml | Failed To Parse BPMN Xml |
+| 400004 | InvalidBpmnWorkflowArgs | Invalid Bpmn Workflow Args |
+| 400005 | FailedToRetrieveXml | Failed to Retrieve BPMN XML |
+| 400006 | BpmnGenericWorkflowFailure | BPMN generic workflow failure |
+| 400007 | BpmnMarkerInputNullError | Input collection for the marker element must not be null |
+| 400008 | BpmnMarkerInputEvaluationFailure | Failed to evaluate the input collection variable for the marker element |
+| 400009 | ElementExecutionLoopDetected | Possible loop detected: element 'X' has been executed more than 100 times. Failing the instance to prevent infinite loop. |
+| 400010 | CaseManagementInvalidJson | Invalid case management process metadata JSON format |
+| 400020 | CreateTriggersForEventSubProcessFailed | Failed to create triggers for Event SubProcess |
+| 400023 | CasePlanOverviewParseError | Failed to retrieve the case plan overview |
+
+## Expression Evaluation (400300–400302)
+
+| Code | Name | Message |
+|------|------|---------|
+| 400300 | InputVariablesEvaluationError | Error evaluating expression in activity inputs |
+| 400301 | ExpressionEvaluationError | Error evaluating expression |
+| 400302 | FlowExpressionEvaluationError | Error evaluating outgoing flow expression from gateway |
+
+## Licensing (400500–400505)
+
+| Code | Name | Message |
+|------|------|---------|
+| 400500 | LicensingClientCanConsumeException | Licensing consumption error |
+| 400501 | LicensingRegisterConsumptionException | Licensing registration error |
+| 400502 | LicensingIsNotValidException | User is not authorized to debug due to missing license |
+| 400503 | LicensingCanConsumeDebugException | User is not licensed to continue |
+| 400504 | LicensingIsNotValidOnRetryException | User is not licensed to continue |
+| 400505 | InvalidLicensingContextFormat | The licensing context format is invalid |
+
+## Auth & Permissions (150001–150009)
+
+| Code | Name | Message |
+|------|------|---------|
+| 150001 | FolderScopedAttributeFolderKeyMissing | Required header 'x-uipath-folderkey' is missing or empty |
+| 150006 | AuthzFolderPermissionMissing | Folder permission missing |
+| 150007 | AuthzFolderPermissionException | Permission denied for folder |
+| 150009 | AccessTokenPrtIdAccountHeaderMismatch | Unauthorized |
+
+## Message Events (450002–450013)
+
+| Code | Name | Message |
+|------|------|---------|
+| 450002 | MaestroMessageSendEventArgsError | Invalid arguments for Message Send Event |
+| 450003 | MaestroMessageSendEventInputError | Invalid input for Message Send Event |
+| 450004 | MaestroMessageReceiveEventArgsError | Invalid arguments for Message Receive Event |
+| 450005 | MaestroMessageBufferingFailure | Failed to buffer message for later consumption |
+| 450006 | MaestroMessagePublishFailure | Failed to publish message |
+| 450007 | MaestroMessageDuplicateSubscriber | Duplicate message subscription detected |
+| 450008 | MaestroMessageSubscriptionFailed | Failed to create message subscription |
+| 450010 | MaestroMessageReceiveFromBlobFailed | No message found |
+| 450011 | MaestroMessageSendEventBlobFailure | Failed to handle message publish |
+| 450012 | MaestroMessageSendFailure | Failed to send maestro message |
+| 450013 | MaestroMessageReceiverNotFound | Message receiver not found |
+
+## Top-20 Production Errors → Playbook Mapping
+
+Ranked by production telemetry volume. Source: [PO.BpmnEngine PR #3092 — `docs/error-catalog.md`](https://github.com/UiPath/PO.BpmnEngine/pull/3092). API-debuggability column tells you whether PIMS APIs alone are enough.
+
+| # | Error | HTTP | Engine code | Orch / connector code | API debug | Playbook |
+|---|-------|:----:|-------------|-----------------------|:---------:|----------|
+| 1 | Personal Automation quota exceeded | 502 | — | 170002 (propagated) | Full | [personal-automation-quota.md](./playbooks/personal-automation-quota.md) |
+| 2 | Job's associated process could not be found | 404 | — | 170007 | Partial | [process-not-found-404.md](./playbooks/process-not-found-404.md) |
+| 3 | No unattended robot permissions in folder | 409 | — | #1671 | Full | [unattended-robot-permissions.md](./playbooks/unattended-robot-permissions.md) |
+| 4 | Job Operation Timeout | 502 | — | — | Partial | [job-operation-timeout.md](./playbooks/job-operation-timeout.md) |
+| 5 | Input does not conform to schema | 400 | — | — | Full | [input-schema-mismatch.md](./playbooks/input-schema-mismatch.md) |
+| 6 | Missing value for required parameter | 400 | — | — | Full | [missing-required-parameter.md](./playbooks/missing-required-parameter.md) |
+| 7 | Generic Error_400 | 400 | — | — | None | [generic-error-400.md](./playbooks/generic-error-400.md) |
+| 8 | Expression evaluation — property not found | 400 | 400300 / 400301 / 400302 | — | Full | [expression-evaluation-errors.md](./playbooks/expression-evaluation-errors.md) |
+| 9 | No outgoing flow condition met | 400 | **400001 (NoOutgoingFlow)** | — | None* | [gateway-no-outgoing-flow.md](./playbooks/gateway-no-outgoing-flow.md) |
+| 10 | Loop detected (>100 executions) | 400 | **400009 (ElementExecutionLoopDetected)** | — | Partial | [loop-detected.md](./playbooks/loop-detected.md) |
+| 11 | 'File' field required | 502 | — | DAP-RT-1003 | Full | [file-field-required.md](./playbooks/file-field-required.md) |
+| 12 | Integration Services 404 | 404 | 102001 (IntSvcResourceNotFound) | — | None | [integration-service-404.md](./playbooks/integration-service-404.md) |
+| 13 | Insufficient funds / Agent Units | 400 | — | — | Full | [insufficient-funds.md](./playbooks/insufficient-funds.md) |
+| 14 | Marker element input collection is null | 400 | **400007 (BpmnMarkerInputNullError)** | — | Partial | [marker-input-null.md](./playbooks/marker-input-null.md) |
+| 15 | Integration Services 400 | 400 | 102003 (IntSvcBadRequest) | — | None | [integration-service-400.md](./playbooks/integration-service-400.md) |
+| 16 | Folder does not exist or no access | 400 | — | #1100 | Full | [folder-not-accessible.md](./playbooks/folder-not-accessible.md) |
+| 17 | No machine with Unattended/NonProduction runtimes | 409 | — | #2818 | Partial | [no-suitable-runtime-machine.md](./playbooks/no-suitable-runtime-machine.md) |
+| 18 | No Message events found | 400 | (450010 if `MaestroMessageReceiveFromBlobFailed`) | — | None | [no-message-events.md](./playbooks/no-message-events.md) |
+| 19 | Foreground job requires unattended robot | 409 | — | #1230 | Full | [foreground-unattended-robot.md](./playbooks/foreground-unattended-robot.md) |
+| 20 | Index outside bounds of array | 502 | — | — | None | [index-out-of-bounds.md](./playbooks/index-out-of-bounds.md) |
+
+> *\* 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 — incident `errorDetails` then includes all outgoing flow conditions, the default flow config, and variable values (truncated to 200 chars) at evaluation time.*

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

@@ -0,0 +1,92 @@
+# Maestro Investigation Guide
+
+## Data Correlation
+
+Before using any fetched data, verify it matches the user's reported problem:
+
+- **Process/Solution** — the BPMN process name and solution match what the user reported
+- **Instance** — the process instance ID matches the specific execution the user is investigating
+- **Folder** — data comes from the correct Orchestrator folder (permissions, triggers, and jobs are folder-scoped)
+- **Time window** — timestamps fall within the relevant period the user described
+- **Child Jobs** — if investigating a service task, verify the child job belongs to the correct parent instance. Always check the child job's **error message and final state** — the child's failure reason is often the actual root cause, not the parent's error code. Search for child jobs in all states (Faulted, Stopped, Successful, Running), not just the expected state.
+
+If the data doesn't match: **discard it**. Do NOT use unrelated data as a proxy. Report the mismatch and ask for clarification.
+
+## First Step: Get the Error Code
+
+Always retrieve the error code from the incident before doing anything else. If the user provides a process instance ID or incident ID, query the incident details to get the error code — this is the most reliable way to route to the correct playbook.
+
+Error codes appear in the Maestro incident detail view. Ask the user for the incident ID or process instance ID if not provided. If neither is available, work from the error message text.
+
+Full error code reference: [error_codes.md](./error_codes.md) — all error codes by subsystem with numeric values and messages.
+
+**Always check [summary.md](./summary.md) Top-20 table first** — it lists the highest-volume Maestro errors (by production telemetry) with direct playbook links and marks each one's API debuggability (Full / Partial / None). Route there before walking the range table below.
+
+Quick routing by range:
+
+| Range | Subsystem | Common action |
+|-------|-----------|---------------|
+| 102000–102018 | Integration Service | Check connection config, endpoint URLs, input parameters |
+| 150001–150009 | Auth & Permissions | Check folder permissions for robot/user account |
+| 170000–170041 | Orchestrator Runtime | Check child job errors, robot availability, task inputs |
+| 300200–300208 | Data Fabric | Check file references, connectivity, record operations |
+| 300500–300503 | Script Tasks | Check for browser-only JS APIs; use Jint-compatible code |
+| 400000–400023 | BPMN Elements | Check BPMN model, gateway conditions, marker inputs |
+| 400300–400302 | Expression Evaluation | Check variable names, types, expression syntax |
+| 400500–400505 | Licensing | Check Maestro license entitlement on the tenant |
+
+## Domain-Specific Data Gathering
+
+After the Orchestrator job data bundle (job details, logs, history) is collected:
+
+1. **Determine runtime type** — check the job's `RuntimeType` or `Source` field. If it's a ProcessOrchestration job (Maestro), gather Maestro-specific data below. Standard Orchestrator jobs don't need these steps.
+2. **Determine the Maestro process type** — `bpmn`, `flow`, or `case`. Every Maestro CLI invocation requires this segment (`uip maestro bpmn ...`, `uip maestro flow ...`, `uip maestro case ...`). Identify the type from the source artifact (`.bpmn`, `.flow`, Case JSON), the `processType` field on the instance/incident, or by asking the user. Examples below use `<type>` as a placeholder — substitute the actual type.
+3. **Resolve the Maestro instance ID** — for ProcessOrchestration jobs, the **Orchestrator job key IS the Maestro instance ID**. They are the same GUID. Do NOT use `ParentJobKey` — that is the parent Orchestrator job, not the Maestro instance.
+   - **User provided a job key and `RuntimeType` is `ProcessOrchestration`**: the job key is the instance ID. Go directly to `uip maestro <type> instance get <job-key> -f <folder-key>`.
+   - **User provided a job key and `RuntimeType` is NOT `ProcessOrchestration`** (standard child job): the child job was spawned by a Maestro service task. Check `ParentJobKey` — that parent job's key may be the instance ID. Try `uip maestro <type> instance get <parent-job-key> -f <folder-key>`.
+   - **Neither works**: search with `uip maestro <type> incident summary --output json` to find the `processKey`, then `uip maestro <type> processes incidents <process-key> --folder-key <folder-key>` to find incident records containing the `instanceId`. If the process type is unknown, try each (`bpmn`, `flow`, `case`) in turn.
+   - **`instance list` may return empty** for completed or faulted instances. Always try `instance get` directly before concluding an instance doesn't exist. Do NOT rely on `instance list` alone.
+4. **Full incident details** — `uip maestro <type> instance incidents <instance-id> -f <folder-key>`. This returns `errorDetails` with stack traces. Do NOT use `uip maestro <type> incident summary` — that returns summaries only without error details.
+5. **Element executions** — `uip maestro <type> instance element-executions <instance-id> -f <folder-key>` to see what each element did and where execution stopped.
+6. **Child jobs** — if the process has service tasks, list child jobs and check their state and error messages. The child's failure reason is often the actual root cause.
+
+## Top-20 Error Quick Route
+
+Match the error text/code in the incident to one of the highest-volume Maestro errors before doing a full investigation. Full table with playbook links: [summary.md](./summary.md).
+
+| Symptom hint | Playbook |
+|--------------|----------|
+| `Personal Automation quota` | [personal-automation-quota.md](./playbooks/personal-automation-quota.md) |
+| `job's associated process could not be found` / 170007 | [process-not-found-404.md](./playbooks/process-not-found-404.md) |
+| `unattended robot permissions in the current folder` / #1671 | [unattended-robot-permissions.md](./playbooks/unattended-robot-permissions.md) |
+| `Job Operation Timeout` | [job-operation-timeout.md](./playbooks/job-operation-timeout.md) |
+| `Input does not conform to schema` / `InputArgumentsSchema` | [input-schema-mismatch.md](./playbooks/input-schema-mismatch.md) |
+| `Missing value for required parameter` | [missing-required-parameter.md](./playbooks/missing-required-parameter.md) |
+| `Error_400` (no specific name) | [generic-error-400.md](./playbooks/generic-error-400.md) |
+| `Property 'X' not found against object of type ExpressionDictionary` | [expression-evaluation-errors.md](./playbooks/expression-evaluation-errors.md) |
+| `No condition for an outgoing flow was met` / 400001 | [gateway-no-outgoing-flow.md](./playbooks/gateway-no-outgoing-flow.md) |
+| `Possible loop detected` / 400009 | [loop-detected.md](./playbooks/loop-detected.md) |
+| `"File" field is required` / DAP-RT-1003 | [file-field-required.md](./playbooks/file-field-required.md) |
+| `Request to Integration Services failed with status code '404'` | [integration-service-404.md](./playbooks/integration-service-404.md) |
+| `Insufficient funds` / Agent Units | [insufficient-funds.md](./playbooks/insufficient-funds.md) |
+| `Input collection for the marker element must not be null` / 400007 | [marker-input-null.md](./playbooks/marker-input-null.md) |
+| `Request to Integration Services failed with status code '400'` | [integration-service-400.md](./playbooks/integration-service-400.md) |
+| `Folder does not exist or the user does not have access` / #1100 | [folder-not-accessible.md](./playbooks/folder-not-accessible.md) |
+| `Could not find a machine with Unattended or NonProduction runtimes` / #2818 | [no-suitable-runtime-machine.md](./playbooks/no-suitable-runtime-machine.md) |
+| `No Message events found` / `No File events found` | [no-message-events.md](./playbooks/no-message-events.md) |
+| `Foreground job requires an unattended robot` / #1230 | [foreground-unattended-robot.md](./playbooks/foreground-unattended-robot.md) |
+| `Index was outside the bounds of the array` | [index-out-of-bounds.md](./playbooks/index-out-of-bounds.md) |
+
+## Testing Prerequisites
+
+When testing hypotheses for Maestro issues, gather and verify these before drawing conclusions:
+
+1. **Error code from incident** — always retrieve the error code from the Maestro incident before drawing conclusions. The error code is the primary classifier for Maestro issues
+2. **Maestro service status** — confirm the Maestro service is enabled on the tenant (license revocations silently disable it)
+3. **License entitlement** — confirm the user's license includes Maestro access
+4. **Folder context** — confirm the folder the process runs in; permissions, connections, and triggers are folder-scoped
+5. **Robot account permissions** — verify the robot account has required permissions in the folder (including "Triggers" permission for wait-for scenarios, not just "Connections.View")
+6. **Debug vs deployed mode** — determine if the issue occurs in debug, deployed, or both. Debug runs under the user's identity with `debug_overwrites.json` folder bindings; deployed runs under the robot account with `bindings_v2.json`
+7. **Source artifacts** — request the `.bpmn` file and `bindings_v2.json` when investigating process logic or variable resolution issues
+8. **Instance and incidents** — get the process instance ID from Maestro Instance Management; check for incidents that may not appear in Orchestrator
+9. **Dependencies** — check `## Dependencies` in `overview.md` for cross-product issues (e.g., Integration Service, AI Trust Layer, Semantic Proxy)

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

@@ -0,0 +1,98 @@
+# Maestro
+
+Agentic orchestration platform built on top of Orchestrator. Maestro supports three process authoring styles, each with its own CLI subcommand:
+
+- **BPMN** (`uip maestro bpmn`) — formal BPMN 2.0 process design with swimlanes, gateways, boundary events, service tasks, and multi-instance markers. Authored in Studio Web's BPMN editor (`.bpmn` files). Best for orchestrating long-running, multi-actor business processes with rich exception flow.
+- **Flow** (`uip maestro flow`) — lightweight node-and-edge process design (`.flow` files). Lower ceremony than BPMN; emphasizes connectors, scripts, sub-flows, and human-in-the-loop nodes. Best for connector-heavy automations and quick agent-orchestrated flows.
+- **Case Management** (`uip maestro case`) — case-centric workflows with stages, tasks, SLAs, escalations, triggers, and edges (Case definition JSON). Best for human-driven, evolving work where progress is tracked per case rather than per linear process run.
+
+Processes are designed in Studio Web, deployed as solutions to Orchestrator, and managed through the Maestro Instance Management UI.
+
+## Dependencies
+
+- **Orchestrator** — executes child jobs, manages folders/permissions/assets, hosts releases and triggers
+- **Studio Web** — BPMN process designer, solution packaging, and publishing
+- **Integration Service** — provides connectors (Outlook, Salesforce, etc.) and triggers for event-driven processes
+- **AI Trust Layer** — governs agent execution policies, trace TTL, and LLM access
+- **Semantic Proxy / LLM Gateway** — routes LLM calls for agent tasks; outage blocks agent execution
+- **Data Fabric** — data storage and retrieval for process context, file handling, and context indexes
+
+## Organization Model
+
+```
+Organization (cloud.uipath.com)
+  └── Tenant
+        └── Folder                    ← Resources are folder-scoped
+              ├── Solutions           ← Published BPMN packages
+              ├── Processes/Releases  ← Deployed entry points
+              ├── Instances           ← Running BPMN process instances
+              ├── Incidents           ← Faults within instances (not always visible in Orchestrator job state)
+              ├── Connections         ← Integration Service connections
+              ├── Triggers            ← IS and queue-based triggers
+              └── Jobs                ← Child jobs spawned by service tasks
+```
+
+## Key Concepts
+
+- **BPMN Process** — the orchestration definition with start events, tasks, gateways, boundary events, and end events
+- **Solution** — a deployable package containing one or more BPMN processes, exported from Studio Web
+- **Instance** — a running execution of a BPMN process
+- **Incident** — a fault within an instance; Maestro captures these even when Orchestrator job state does not reflect them
+- **Service Task** — a BPMN task that invokes a child Orchestrator job (robot workflow or agent)
+- **Human Task** — a BPMN task that creates an action for a human user
+- **Agent Task** — a service task that invokes an AI agent with context and tools
+- **Multi-Instance Marker** — a parallel execution marker on a task node; iterates over a collection variable (batch limit: 50)
+- **Boundary Event** — error or timer event attached to a task; catches faults or timeouts and redirects flow
+- **Exclusive Gateway** — conditional branching based on variable expressions (case-sensitive)
+- **bindings_v2.json** — maps folder references and variable bindings for deployed mode
+- **debug_overwrites.json** — redirects folder bindings during debug mode (not used in deployed mode)
+
+## CLI
+
+Maestro CLI commands are namespaced by process type. Pick the subcommand that matches the process:
+
+| Process type | Subcommand | Source artifacts | One-liner |
+|--------------|------------|------------------|-----------|
+| BPMN | `uip maestro bpmn ...` | `.bpmn` files (Studio Web BPMN editor) | Formal BPMN 2.0 with swimlanes, gateways, boundary events, service/human/agent tasks |
+| Flow | `uip maestro flow ...` | `.flow` files | Lightweight node-and-edge orchestration; connector-heavy, lower ceremony than BPMN |
+| Case | `uip maestro case ...` | Case definition JSON | Case-centric work with stages, tasks, SLAs, escalations, and triggers |
+
+**Identify the process type first** — check the source artifact, the `processType` field on incidents/instances, or ask the user. Running `uip maestro bpmn instance get <id>` against a Flow instance returns no data. Substitute `<type>` below with `bpmn`, `flow`, or `case`.
+
+```
+uip maestro <type> process list|get|run                          — list/get/run processes
+uip maestro <type> job traces|status <job-key>                   — stream traces or get status for a job
+uip maestro <type> instance list [-f <folder-key>]               — list instances. Filters: --process-key, --error-code, --limit, --offset
+uip maestro <type> instance get <id> [-f <folder-key>]           — get instance details
+uip maestro <type> instance incidents <id> [-f <fk>]             — full incidents with errorDetails and stack traces
+uip maestro <type> instance element-executions <id> [-f <fk>]    — element execution history
+uip maestro <type> instance variables <id> [-f <fk>]             — instance variables. Filter: --parent-element-id
+uip maestro <type> instance asset <id> [-f <fk>]                 — process definition asset (BPMN XML, Flow JSON, Case JSON)
+uip maestro <type> instance cursors <id> [-f <fk>]               — current execution cursor positions
+uip maestro <type> instance retry <id> [-f <fk>]                 — retry a faulted instance
+uip maestro <type> instance pause|resume|cancel <id> [-f <fk>]   — lifecycle control
+uip maestro <type> processes incidents <key> [--folder-key <fk>] — incidents across all instances of a process
+uip maestro <type> incident summary                              — tenant-level incident SUMMARIES ONLY (no errorDetails)
+uip maestro <type> incident get <incident-id>                    — get a single incident by ID
+```
+
+Key commands for troubleshooting (substitute `<type>` with `bpmn`, `flow`, or `case`):
+- `uip maestro <type> instance incidents <instance-id> -f <folder-key>` — **full incident details** including `errorDetails` with stack traces. Use this, not `incident summary`.
+- `uip maestro <type> instance element-executions <instance-id> -f <folder-key>` — what each element did
+- `uip maestro <type> processes incidents <process-key> --folder-key <fk>` — incidents across all instances of a process
+
+**WARNING:** `uip maestro <type> incident summary` returns only aggregated summaries (counts, error codes) without `errorDetails`. It does NOT contain stack traces or full error messages. Always use instance-level or process-level incident commands for troubleshooting.
+
+**WARNING:** There is no top-level `uip maestro instance` / `uip maestro process` / `uip maestro incident` command — every operation requires the `bpmn`, `flow`, or `case` segment. Running the old un-namespaced form fails.
+
+## Features
+
+- **BPMN Process Design** — visual process editor in Studio Web with swimlanes, gateways, and markers
+- **Solution Deployment** — package and deploy BPMN processes to Orchestrator folders
+- **Instance Management** — monitor and manage running process instances and incidents
+- **Human-in-the-Loop** — assign tasks to human users with approval/input forms
+- **Agent Orchestration** — invoke AI agents as service tasks with context indexes and tools
+- **Multi-Instance Parallel Execution** — run tasks in parallel over a collection (batch limit: 50)
+- **Integration Service Triggers** — start processes from external events (email, webhook, etc.)
+- **Boundary Events** — error and timer handlers on tasks for exception flow
+- **Variable Expressions** — JavaScript (Jint) or C# expressions for conditions and transformations

package/skills/uipath-troubleshoot/references/products/maestro/playbooks/agent-traces-disappearing.md

@@ -0,0 +1,22 @@
+---
+confidence: high
+---
+
+# Agent Traces Disappearing
+
+## Context
+
+What this looks like:
+- Agent execution traces are missing
+- Traces disappear after hours or days
+
+What can cause it:
+- Trace TTL (Time-To-Live) in AI Trust Layer policies is set to a short retention period (1 day or 7 days), automatically deleting traces
+
+## Investigation
+
+1. Check AI Trust Layer policies in the admin page for the Trace TTL setting
+
+## Resolution
+
+- Adjust or disable the Trace TTL setting in AI Trust Layer policies to retain traces for the required period