Debugging

Debugging means running your playbook to see what it really does, find where it fails and fix it. The Designer lets you run it on your own machine as many times as you want before publishing it to Zoan Cloud, so you catch problems while you can still see them.

Test locally before publishing

A bot in production runs on its own and often without a screen. Any problem is harder to diagnose there. Golden rule: make the playbook run reliably in the Designer before publishing it.

Run and debug

The top bar gives you two ways to start the open playbook:

Action	Shortcut	What it does
Run	F5	Runs the playbook from start to finish, as a robot would.
Debug	F6	Runs the playbook with the debugger: it stops at breakpoints, lets you step through it and shows variable values at every pause.

Both use the same engine as Zoan Cloud robots, so what works in the Designer works the same once published.

Before running, the Designer checks two things:

• That there are no errors. It analyzes the playbook and the ones it invokes. If any has errors (an invalid expression, an undeclared variable…), it doesn’t run and shows the list so you can jump to each one: a playbook with errors would fail halfway, perhaps after changing things in SAP, Excel or the web. It doesn’t let you publish with errors either. You don’t have to wait until you run to see them: the Problems panel shows them live while you design.
• That you’re signed in to Zoan Cloud with an environment selected. The run is recorded in Zoan Cloud and uses its credentials, queues and processes. If you aren’t signed in, it asks you to.

While it runs, the card of the running activity is highlighted on the canvas, and finished ones are marked with their duration, so you see exactly where the flow is.

Stop (⇧F5) asks the process to stop when it finishes what it is doing (see Should Stop): the bar shows Stopping… and the run ends as stopped, in Zoan Cloud too. Meanwhile Terminate appears to cut it right away; then it is recorded as cancelled (not failed). While debugging, Stop cuts it right away.

Breakpoints

A breakpoint stops the run before an activity so you can look at the state at that moment.

• Click the activity’s number in the canvas’s left margin, or select it and press F9. A red dot appears.
• Click again (or F9) to remove it. Ctrl+⇧F9 removes them all.
• They’re saved with the project: they’re still there next time you open it.
• You can add and remove them while debugging.

The Breakpoints tab of the bottom panel lists all of the project’s breakpoints, grouped by playbook: click one to go to its activity, remove them one by one or all at once.

The debug bar

While debugging, the center of the top bar becomes the debug bar (search is still available with Ctrl+K). Each button has its icon and name, and the bar takes the color of the state: cyan while running, amber when paused and red if it stopped on an error.

Button	Shortcut	What it does
Continue	F5	Runs until the next breakpoint or the end.
Pause	—	Stops before the next activity.
Step over	F10	Runs the current activity completely (with everything inside it) and stops at the next one.
Step into	F11	Goes into the current activity: if it’s a container (If, For Each, a scope…) or invokes another playbook, it stops at its first step.
Step out	⇧F11	Finishes the current container or playbook and stops when leaving it.
Run to here	Ctrl+F10	Runs until the activity you have selected, like a one-time breakpoint.
Go to step	—	Selects the running (or paused) activity and brings it into view.
Restart	Ctrl+⇧F5	Stops the run and debugs again from the start.
Stop	⇧F5	While debugging, ends the run right away (recorded as cancelled).
Options	—	Slow step, log activities, pause on errors and the breakpoints panel.

The same controls are in the ☰ → Debug menu.

When an activity fails

While debugging, an error nobody catches (outside a Try / Catch) stops the run on the failing activity instead of ending it. The card turns red with the message, and the bar offers:

• Retry: runs the same activity again. Useful if you fixed something in the application or the data.
• Ignore: treats the activity as done and moves on to the next one.
• Continue: lets the error run its course (the run ends as failed, or an outer Try / Catch catches it).

Debug options

Options (or ☰ → Debug) has three settings that are remembered between sessions and can be changed mid-debug. The Options button is tinted when any of them isn’t at its default.

Option	What it does
Slow step	Waits before each activity (0.25, 0.5, 1 or 2 s) so you can follow the run by eye.
Log activities	Writes each activity to the console as it starts (▶ 4 · Log).
Pause on errors	On by default: stops on the failing activity (see above). Off, the run ends with the error, as in production.

Inspect variables

At every pause, the right panel shows:

• Locals: every variable with its value at that moment.
• Watch: expressions you choose to follow (for example rows.Count or customer.Name), evaluated at every pause.

The Call stack tab of the bottom panel shows where the run is stopped: the current activity and the containers around it, from the inside out, up to the playbook. Click any of them to go there.

When a run ends, select an activity with an output: the Preview (last run) section in Properties shows the value it produced (for a table, its first rows; a click opens it in full). If the playbook failed writing an Excel file, check what the table really held: maybe it was empty or had an unexpected value.

Read the console

The Console tab shows, live:

• The messages you write with the Log activity, with their level.
• Errors and their details when something fails.
• The start and end of the run, with its duration.

Each line shows the playbook that produced it. When a playbook invokes another, its lines appear with ↳ and indented per level, so you always know where each message comes from:

23:16:37.260  INFO   Main                  starting the main playbook
23:16:37.271  INFO   ↳ Load customers      reading the customer file
23:16:37.277  WARN     ↳ Validate row      validating row 1
23:16:37.292  INFO   ↳ Load customers      customers loaded
23:16:37.295  INFO   Main                  back in the main playbook
23:16:37.304  OK                           Run finished successfully · 767 ms

Console text can be selected and copied; Copy all copies the whole log (with each line’s playbook) and Clear empties it.

Log levels

The Log activity lets you write messages with a severity level. Use them to leave “breadcrumbs” that explain what’s happening:

Level	When to use it
debug	Fine detail for deep diagnosis
info	Normal milestones (“10 invoices read”)
warning	Something unexpected but not fatal (“customer without email, skipped”)
error	A failure that prevents continuing

Log with intent

Adding Log activities at key points (after reading data, before a critical action, inside a catch) turns an opaque failure into an easy-to-locate problem. In production, the same messages appear in Zoan Cloud’s execution logs.

Handle errors without stopping the bot

Not every error should stop the run. For the ones you expect (an email without an attachment, a page that is sometimes slow), use these two Core activities:

Try / Catch

Runs the activities in the Try lane; if any fails, the flow jumps to the Catch lane, where you can log the error and carry on with a plan B instead of stopping. Finally always runs. See Try / Catch.

Try Catch   errorVariable = error
├─ Try:
│    Read Excel Sheet   → table
├─ Catch:
│    Log   level = "error"   message = "Could not read the Excel file: " + error.Message

errorVariable receives a ZoanError: error.Message is the message and error.Type the type, useful to handle each kind of error differently.

Retry

Retries a group of activities several times before giving up. Ideal for actions that fail intermittently (the network, a slow page). See Retry.

Retry   attempts = 3   delay = 2000
└─ Body:
     Click   selector = (captured with UI Discover)

A business exception (data that prevents going on) is not retried: retrying wouldn’t fix it.

Attended vs unattended

An error that only happens in production is often caused by a different environment: the bot runs headless (no window), with another screen resolution, another Windows session or without the application open. If something works in the Designer but fails once published, test locally under the same conditions (for example headless = true in Open Browser, or Hidden in the project settings).

Go to the activity of an error

When an execution fails, the console says Where it happened: the file, the step, the activity and, if it applies, the parameter, with the chain of playbooks that led there (for example “main.play › Pasos.play · step 2 “Set Variable” · parameter “Value""). Go to the activity opens that playbook at that card. If the error was caught and thrown again with Throw (the templates’ pattern), the location is still the one of the original error.

When an error comes from outside the Designer (a Zoan Cloud log, an alert email, a colleague), you don’t have to look for the activity by hand: open the command palette (Ctrl+K) and paste the error message, the activity id or the execution id. The Designer offers Go to the activity, or Go to the error of execution… to read that execution’s error in your environment, and takes you to the activity and the parameter where it happened.

Common errors

Error	Likely cause	Fix
”Fix the errors before running”	The playbook or one it invokes has errors	Click each error in the list to go to it and fix it
”Sign in to run”	No Zoan Cloud session or no environment selected	Sign in from the avatar in the top bar and pick the environment
”Unknown activity or missing type”	The activity uses a package that isn’t installed	Install it from the Package manager (rail → Packages)
“The name ‘x’ does not exist in the current context”	A variable was used without declaring it	Declare it (Ctrl+Shift+V from the field) or fix the name
Incompatible type	An expression’s result isn’t the type the field expects	Check the types in the variables panel and convert the value
Element not found / Selector not found	The page or app changed, or hadn’t finished loading	Add a wait before it, adjust the selector or raise the timeout
Timeout	The action took longer than the limit	Raise the activity’s timeout or the one in the project settings

Next steps

• Project settings — UI timeouts and delays for the whole project.
• Expressions — fix formulas that return unexpected values.
• Execution logs — debug what already runs in production.
• States and lifecycle — understand why a run ends up failed.