UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

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 a project.uiproj.

Options​

OptionDefaultDescription
--folder-id <id>auto-detectedOrchestrator 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>2000Polling interval in milliseconds while waiting for Studio Web to advance the session.
--timeout <seconds>no limitMaximum 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 triggerEntry 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>10Minimum minutes before token expiration to trigger an automatic refresh.

Behavior​

  1. Validates login and pulls the organization, tenant, base URL, organization name, and auth token from the session.
  2. Uploads the project to Studio Web under the target folder.
  3. 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]
    
  4. On incidents during the run, emits a warning line.
  5. Exits 0 if finalStatus is Completed or Successful; 1 otherwise.

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"
  }
}
FieldDescription
failedElement executions that did not complete, as { elementId, status }. Empty for a clean run.
outputsThe 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.
missingOutputsDeclared outputs the run's record did not carry.
incidentsIncidents raised during the run, when there are any.
fullOutputPathWhere the full result was written.
fullOutputErrorWhy 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​

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated