Observability and Debugging
Debug workflow failures and investigate hosted workflow runs.
Recordings and debug context
Hosted workflow runs capture a browser recording unless you create them with
headless: true or the run fails before a browser starts. Use the recording with job state, logs, screenshots, and failure reports to understand what happened during the run.Use
/v1/jobs/get for status, params, timestamps, result or error, and mapped stack.Use
/v1/recordings/get with a job_id or session_id when you need a recording URL. Recording URLs are temporary; call the same endpoint again to generate a fresh URL after one expires.Use
/v1/jobs/debugReport for failed-run diagnosis, fix instructions, artifact links, job error details, and auto-repair fields when available.Use
/v1/logs/list for workflow logs and Libretto executor logs from the job, filtered by jobId, workflow, or severity.See Jobs and Logs for the full API reference.
Job results stay for the life of your workspace. Screenshots, logs, and recordings have shorter windows. See Data retention.
Failure emails
By default, when a Libretto Cloud workflow job fails, Libretto Cloud starts a debug agent to analyze the failed run. The agent emails the configured debug recipient with:
- A short diagnosis. What failed and why.
- A handoff prompt for your local coding agent. Includes the diagnosis and instructions for fixing the workflow.
- Links to relevant debug context. Includes recordings, screenshots, and logs when available.
The email is designed to move the fix back into a local coding workflow quickly. After you receive it, use the local repo and Libretto tooling to inspect the failure and patch the workflow.
For the local debugging flow, see Debugging workflows.
Auto-repair
Auto-repair lets Libretto Cloud try to fix failed workflows for you. When a job fails, an autofix agent analyzes the run, edits the deployed workflow code, and publishes a replacement deployment when it has a fix.
Use
--auto-repair when deploying from the CLI:1npx libretto cloud deploy my-automations --auto-repair