Skip to main content
Popup Recovery handles unexpected dialogs, overlays, banners, and other blocking UI states without making consequential choices on your behalf.
  • For an ACTION_REQUIRED blocker, the agent confirms that it is visible and uses a targeted action to close it. If the blocker is no longer present, the recovery action safely does nothing.
  • For a DECISION_REQUIRED state, the agent asks a person instead of choosing blindly; see Decision Required.
Enable Popup Handling in Maintenance Agent Settings. You can also configure known dismiss controls with popup_xpaths; see Workflow Settings.

XPath Recovery

XPath Recovery handles eligible Click and Input Text steps when a selector no longer finds the intended element, matches multiple elements, or resolves to the wrong element shape. The agent uses the current page, failed selector, match count, failure subtype, and step description to perform the intended action with AI and resume after the failed step. Recovery is bounded and stops safely when the required page context is unavailable or recent attempts for the same step have repeatedly failed. Enable XPath Recovery in Maintenance Agent Settings. This runtime recovery does not guarantee that the workflow’s stored selector will be permanently replaced.

Page Loading Recovery

Page Loading Recovery handles actions that run before the relevant page or component is ready. It applies to Click, Input Text, Input Select, Scroll, and Extract Datamodel nodes. The agent waits 10 seconds for any loading state. Actions that fired too early (PREMATURE_ACTION) are not given a wait. On the first eligible failure for a step, the agent injects a temporary 10-second Delay and retries the action. Attempts are tracked per step and session to prevent loops. If the retry still fails, the agent can retrace to an earlier eligible step when enough run context is available. A full requeue is the final fallback when Service Unavailable Recovery is enabled. Page Loading Recovery is controlled by Action Timing Recovery (enable_action_timing_recovery). It is enabled by default but can be disabled at the workspace or workflow level.

Password Update Recovery

Password Update Recovery handles password-expiration and mandatory-rotation screens while keeping the vault credential current.
  1. The agent distinguishes an optional prompt from a mandatory password-change form.
  2. Optional prompts can be dismissed.
  3. For a mandatory update, the agent reads the current vault credential and visible password requirements.
  4. It generates a compatible password, fills the required fields, and submits the form.
  5. After success, it updates the vault and sends an execution.password_updated webhook.
  6. The workflow resumes using the updated credential.
Enable Password Update Recovery in Maintenance Agent Settings or set enable_password_update_recovery through the Workflow API.
Automatic rotation requires exactly one vault credential on the workflow. When multiple credentials are present, CloudCruise does not guess which credential to rotate and sends a notification instead. Provider-backed credentials are written back to the connected provider; see the 1Password integration.

2FA Setup

When a site forces two-factor authentication enrollment mid-run, the failure is classified as action required and handed to the recovery agent, which works the screen using the workflow’s vault credentials. If the agent cannot complete the enrollment, the run reports that action is required. The separate enable_tfa_setup_recovery setting is deprecated and has no effect.

Security Question Recovery

When a site asks a security question that no workflow node handles, and the run’s vault credential has stored security questions, the recovery agent answers it from the vault. It matches the page question as a SECURITY_QUESTION node with fuzzy_match does. If no stored question matches, the agent requests a decision instead.

Service and Logged-Out Session Recovery

Service Unavailable Recovery requeues transient external failures such as application errors, HTTP errors, timeouts, and active maintenance windows. A permanently retired service is reported but not retried. Logged-out sessions use the same retry setting. When a site expires or invalidates a session during a workflow, CloudCruise notifies your configured channels and can requeue with stored cookies and browser state cleared, giving the next attempt a clean authentication path. A silent login failure may also receive one bounded retry when retry recovery is enabled and the workflow has succeeded recently. The retry delay follows 10 minutes × 2^n, where n begins at 0, with ±20% jitter: Enable Service Unavailable Recovery and set Maximum Error Recovery Attempts from 0 to 10. While waiting, the run status is execution.requeued; it does not report execution.failed unless the retries run out. The corresponding webhook includes the retry attempt and scheduled execution time. See Run Statuses.

Repair the workflow

Automatic recovery keeps the current run moving. When a workflow needs a permanent change, the run details page provides repair tools for members with the appropriate permissions:
  • Manual XPath correction lets you review a suggested selector against the captured DOM and save a corrected workflow version.
  • Edit Workflow opens the workflow directly for manual changes.
  • Fix with Builder Agent starts an interactive repair session with the failed workflow, failing step, and run inputs already selected.
  • Adopt fix with Builder Agent may appear to workspace admins for eligible repeated popup recoveries. Dismissible popups require a validated reusable selector; decision-required popups are handed to the Builder Agent without pinning a choice automatically.