- Overview
- Get started
- Concepts
- Using UiPath CLI
- How-to guides
- CI/CD recipes
- Command reference
- Overview
- Exit codes
- Global options
- uip codedagent
- uip coder
- uip context-grounding
- uip docsai
- uip function
- uip guardrails
- uip llm-configuration
- uip llm-gateway
- uip maestro authoring
- uip maestro registry
- uip model-hub
- activities find
- activities get-default-xaml
- analyze
- analyzer-rules list
- build
- cleanup
- data-fabric-entities install
- data-fabric-entities list
- files diff
- get-library-object-repository
- get-object-repository
- init
- instances list
- pack
- packages inspect
- packages install
- packages versions
- publish
- remote
- restore
- run, debug & execution
- settings
- studio start
- templates search
- test-data add-entity
- test-data add-queue
- test-data add-variation
- tm
- uia
- validate
- workflow-examples get
- workflow-examples list
- uip tasks
- uip traces
- uip traces feedback
- Migration
- Reference & support
uip maestro flow debug
Syntax and options for `uip maestro flow debug`, which uploads a local Flow project to Studio Web and runs a server-side debug session with streamed status updates.
uip maestro flow debug uploads a local Flow project to Studio Web and runs a server-side debug session, streaming per-element status updates back to the console and returning a final status.
Synopsis
uip maestro flow debug <project-path>
[--folder-id <id> | --folder-key <key> | --folder-path <path>]
[--poll-interval <ms>] [--timeout <seconds>]
[-i, --inputs <json>]
[--entry-point <id>]
[--attachment <name=path>]...
[--summary]
[--open-in-browser]
[--login-validity <minutes>]
uip maestro flow debug <project-path>
[--folder-id <id> | --folder-key <key> | --folder-path <path>]
[--poll-interval <ms>] [--timeout <seconds>]
[-i, --inputs <json>]
[--entry-point <id>]
[--attachment <name=path>]...
[--summary]
[--open-in-browser]
[--login-validity <minutes>]
Requires uip login. Honors global options. Exit codes follow the standard contract.
Arguments
<project-path>(required) — path to the Flow project directory. Must contain aproject.uiproj.
Options
| Option | Default | Description |
|---|---|---|
--folder-id <id> | auto-detected | Orchestrator folder (OrganizationUnitId), a positive integer. Mutually exclusive with --folder-key/--folder-path. If none of the three are given, the folder on the current login session is used. |
--folder-key <key> | — | Orchestrator folder key (UUID) — resolved to the folder ID by the CLI. Mutually exclusive with --folder-id/--folder-path. |
--folder-path <path> | — | Orchestrator folder path, e.g. Shared/Sub — resolved to the folder ID by the CLI. Mutually exclusive with --folder-id/--folder-key. Use uip or folders list to discover valid keys/paths. |
--poll-interval <ms> | 2000 | Polling interval in milliseconds while waiting for Studio Web to advance the session. |
--timeout <seconds> | no limit | Maximum seconds to wait for the debug run to finish. When it elapses, the command fails with ErrorCode: timeout and Retry: RetryLater, and Data carries instanceId, jobKey, lastStatus, and timeoutSeconds. The run is not stopped. Has no effect on a conversational flow, which is handed off without polling. |
-i, --inputs <json> | — | Input arguments as a JSON string, or @path/to/file.json to read from a file. |
--entry-point <id> | default trigger | Entry point node ID — a trigger node ID from the .flow file. Defaults to the trigger marked isDefaultEntryPoint, else the first trigger. An ID that matches no trigger fails with exit code 3. |
--attachment <name=path> | — | Upload a local file to Orchestrator and bind it as a file-type input variable. Repeatable, e.g. --attachment file1=./resume.pdf. Overrides the same variable name if also present in --inputs. |
--summary | — | Return only the run status, the elements that did not complete, and the flow's declared outputs, instead of every node's raw output. Refer to Summary output. |
--open-in-browser | — | Open the Studio Web session URL in a browser once available. |
--login-validity <minutes> | 10 | Minimum minutes before token expiration to trigger an automatic refresh. |
Behavior
- Validates login and pulls the organization, tenant, base URL, organization name, and auth token from the session.
- Uploads the project to Studio Web under the target folder.
- Polls for a final status, emitting per-element status lines like:
Status: InProgress (2/5 elements completed) v Node_1 [Completed] > Node_2 [InProgress] - Node_3 [NotStarted]Status: InProgress (2/5 elements completed) v Node_1 [Completed] > Node_2 [InProgress] - Node_3 [NotStarted] - On incidents during the run, emits a warning line.
- Exits
0iffinalStatusisCompletedorSuccessful;1otherwise.
Examples
# Debug a local project, auto-detect folder, default poll interval
uip maestro flow debug ./invoice-flow
# Debug against a specific folder with inline JSON inputs
uip maestro flow debug ./invoice-flow --folder-id 2553016 \
--inputs '{"amount":100,"customer":"Acme"}'
# Debug with inputs from a file
uip maestro flow debug ./invoice-flow --inputs @inputs.json
# Slower polling for long-running flows
uip maestro flow debug ./invoice-flow --poll-interval 5000
# Start from a specific trigger and stop waiting after 10 minutes
uip maestro flow debug ./invoice-flow --entry-point trigger_2 --timeout 600
# Read only the verdict and the declared outputs
uip maestro flow debug ./invoice-flow --summary
# Debug a local project, auto-detect folder, default poll interval
uip maestro flow debug ./invoice-flow
# Debug against a specific folder with inline JSON inputs
uip maestro flow debug ./invoice-flow --folder-id 2553016 \
--inputs '{"amount":100,"customer":"Acme"}'
# Debug with inputs from a file
uip maestro flow debug ./invoice-flow --inputs @inputs.json
# Slower polling for long-running flows
uip maestro flow debug ./invoice-flow --poll-interval 5000
# Start from a specific trigger and stop waiting after 10 minutes
uip maestro flow debug ./invoice-flow --entry-point trigger_2 --timeout 600
# Read only the verdict and the declared outputs
uip maestro flow debug ./invoice-flow --summary
Data shape (--output json)
{
"Code": "FlowDebug",
"Data": {
"jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
"instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
"runId": "d4e5f6a7-0000-0000-0000-000000000001",
"finalStatus": "Completed",
"solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
"studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
"elementExecutions": [
{ "elementId": "Node_1", "status": "Completed" }
],
"variables": {}
}
}
{
"Code": "FlowDebug",
"Data": {
"jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
"instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
"runId": "d4e5f6a7-0000-0000-0000-000000000001",
"finalStatus": "Completed",
"solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
"studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
"elementExecutions": [
{ "elementId": "Node_1", "status": "Completed" }
],
"variables": {}
}
}
Open studioWebUrl in a browser to inspect the session interactively.
Summary output
The full result holds every node's output next to the flow's declared outputs, including whole HTTP response bodies and headers. With --summary, Data holds only what you need to judge the run:
{
"Code": "FlowDebug",
"Data": {
"finalStatus": "Completed",
"instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
"studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
"solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
"failed": [],
"outputs": { "weatherVerdict": "warm office today" },
"fullOutputPath": "/path/to/solution/.flow-debug/invoice-flow.json"
}
}
{
"Code": "FlowDebug",
"Data": {
"finalStatus": "Completed",
"instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
"studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
"solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
"failed": [],
"outputs": { "weatherVerdict": "warm office today" },
"fullOutputPath": "/path/to/solution/.flow-debug/invoice-flow.json"
}
}
| Field | Description |
|---|---|
failed | Element executions that did not complete, as { elementId, status }. Empty for a clean run. |
outputs | The flow's declared output variables (out and inout), by ID. Absent when the variables could not be read. variablesError then says why, and the outputs are unknown, not empty. |
missingOutputs | Declared outputs the run's record did not carry. |
incidents | Incidents raised during the run, when there are any. |
fullOutputPath | Where the full result was written. |
fullOutputError | Why the full result could not be written. The summary still stands. |
The full result — what the command prints without --summary — is written to <solution>/.flow-debug/<project>.json, where <solution> is the folder that holds the .uipx file and <project> is the project path relative to it. The file is replaced on every run.
The file holds tenant data, so the CLI also writes .flow-debug/.gitignore with *, and uip solution pack and uip solution upload skip the folder.
Conversational-trigger handoff
A Flow whose entry point is core.trigger.conversation can only be driven by a chat UI — the CLI cannot start a debug session for it. Instead, it uploads the project to Studio Web and hands off:
{
"Code": "FlowDebugStudioWebHandoff",
"Data": {
"solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
"studioWebUrl": "https://cloud.uipath.com/org/studio_/designer/a1b2c3d4?solutionId=e5f6a7b8",
"handedOff": true
}
}
{
"Code": "FlowDebugStudioWebHandoff",
"Data": {
"solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
"studioWebUrl": "https://cloud.uipath.com/org/studio_/designer/a1b2c3d4?solutionId=e5f6a7b8",
"handedOff": true
}
}
No elementExecutions/finalStatus fields are present — nothing was run, so there's nothing to poll. Pass --open-in-browser to have the CLI open studioWebUrl automatically.
Faulted run — inline incidents
A faulted run is returned as a Result: "Failure" envelope (exit code 1), with incident details already inline on Data.incidents — no follow-up command is needed to see what broke:
{
"Code": "FlowDebug",
"Data": {
"jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
"instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
"runId": "d4e5f6a7-0000-0000-0000-000000000001",
"finalStatus": "Faulted",
"incidents": [
{
"incidentId": "inc-1",
"elementId": "Node_3",
"errorCode": "Process.UnhandledException",
"errorMessage": "Object reference not set to an instance of an object."
}
]
}
}
{
"Code": "FlowDebug",
"Data": {
"jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
"instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
"runId": "d4e5f6a7-0000-0000-0000-000000000001",
"finalStatus": "Faulted",
"incidents": [
{
"incidentId": "inc-1",
"elementId": "Node_3",
"errorCode": "Process.UnhandledException",
"errorMessage": "Object reference not set to an instance of an object."
}
]
}
}
On a faulted run, the error Instructions point you at uip maestro flow debug-instance incidents <instanceId> to inspect the raw backend payload — see debug-instance for that lower-level control surface.
See also
uip maestro flow debug-instance— step-by-step control over a debug session, for building custom toolinguip maestro flow validate— static check before runninguip maestro flow process run— run a published processuip maestro flow job traces— stream traces for an already-started job- Authentication
- Flow overview