Debugging

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

Prueba local antes de publicar

A bot in production runs alone and often without a screen. Any problem is harder to diagnose there. The golden rule: make sure the playbook works stably in Designer before publishing it.

Run locally

Local execution uses Agent installed on your same machine, so make sure it is running first.

1. Verify that Zoan Agent is active (its icon appears in the system tray, next to the clock).
2. In the Designer toolbar, click Run (button with play icon).
3. The playbook starts running and the logs panel (bottom) shows the messages in real time.

As it runs, the Designer highlights the activity in progress, so you see exactly where the flow is going.

Read the log panel

During and after the execution, the logs panel shows you:

• The messages that you issue with the Log activity.
• The activity that is being executed at each moment.
• The errors and their detail (stack trace) when something fails.
• The time of execution.

Locate the failing activity

Every activity on the canvas has a global number (#N) that does not reset inside lanes: it is unique across the whole playbook, in execution order. When an activity fails, the logs panel shows a #N · label chip you can click to select and center the culprit activity on the canvas — much faster than finding it by its id.

[INFO] Iniciando ejecución
[INFO] browser-open: chrome → erp.cliente.com
[INFO] page-fill: #usuario
[WARN] page-wait-for: reintentando (1/3)
[ERROR] page-click: selector "#guardar" no encontrado tras 10000ms
[FAIL]  Ejecución detenida — 8.7s

Niveles de log

The Log activity lets you write messages with a level of severity. Use them to leave “footprints” that explain what is happening:

Nivel	When to use it
debug	Fine detail for deep diagnosis
info	Normal process milestones (“10 invoices read”)
warning	Something unexpected but not fatal (“client without mail, skipped”)
error	A failure that prevents you from continuing

Log with intention

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

Inspeccionar variables

Upon completion of an execution—whether it was successful or not—the variables panel displays the final value of each variable. This is key for debugging: if the playbook failed to write an Excel, check what the variable actually had with the table; Maybe it arrived empty or with unexpected information.

Handle errors without stopping the bot

Not all errors should bring down execution. For those you wait (an email without an attachment, a page that sometimes takes a while), use these two activities from the Core package:

Try / Catch

Executes the activities of lane try; if any failure, the flow jumps to lane catch, where you can log the error and continue with a plan B instead of stopping. See Try / Catch.

Try/Catch   errorVariable = error
├─ try:
│    Excel Read Range   → tabla
├─ catch:
│    Log   level = error   message = = "No se pudo leer el Excel: " + error

errorVariable saves the error message as text, so it is read directly with = error (not error.Message).

Retry

You retry 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:
     Page Click   selector = "#guardar"

Atendido vs desatendido

Reproducing an error that only occurs in production is often due to environment differences: the bot runs headless (without a window), with another screen resolution, another Windows session or without the application open. If something works in the Designer but fails published, try locally with the same conditions (for example, headless = true in Open Browser).

Common errors

Error	Causa probable	Solution
Agent no disponible	Agent is not running	Open it from the start menu and wait for it to connect
Package not installed	The activity uses a package missing from the Agent	Install it from Zoan Cloud → Packages
Variable no declarada	A variable was used without declaring it	Declare it on the panel or correct the name
Incompatible type	The result of one activity is not of the type expected by the next	Check the types in the variables panel; converts with toNumber, toString, etc.
Selector no encontrado	The page/app changed, or had not finished loading	Add a Page Wait For before, or adjust the selector
Timeout	The action took longer than the time limit	Raise parameter timeout or wait for a precondition

Next steps

• Expressions — fix formulas that return unexpected values.
• Execution logs — debug what is already running in production.
• States and life cycle — understand why an execution remains in failed.