karatelabs/karate · error · UnsupportedOperationException

Dialog callback handler not supported on WebDriver backend…

Error message

Dialog callback handler not supported on WebDriver backend. Use dialog(true/false) after the dialog appears.

What it means

W3cDriver (WebDriver-based drivers) cannot register an async dialog callback handler, so onDialog(DialogHandler) unconditionally throws UnsupportedOperationException. WebDriver's protocol handles JS dialogs synchronously; the callback style is only available on backends like Chrome DevTools-based drivers. The message directs users to the dialog(true/false) API.

Solutions

Remove the onDialog call and instead call driver.dialog(true) (accept) or driver.dialog(false) (dismiss) after the dialog appears
Use a CDP-backed driver (e.g. chromedriver via DevTools) if callback-style dialog handling is required
Guard the setup with a driver-type check so shared code skips onDialog on WebDriver backends
Avoid triggering native alert/confirm/prompt in WebDriver tests when possible; use in-page dialogs instead

Example fix

// before
driver.onDialog(dialog -> dialog.dismiss()); // throws on WebDriver backend
// after
// no onDialog; when a dialog appears:
driver.dialog(false); // dismiss it synchronously

Defensive patterns

Strategy: fallback

Validate before calling

// detect WebDriver backend before using callback API
boolean isWebDriver = driver instanceof io.karatelabs.driver.w3c.W3cDriver;

Type guard

if (driver instanceof io.karatelabs.driver.w3c.W3cDriver) {
    // WebDriver backend: use dialog(true/false) flow
} else {
    driver.onDialog(handler);
}

Try / catch

try {
    driver.onDialog(handler);
} catch (UnsupportedOperationException e) {
    // fall back to dialog(true/false) after the dialog appears
    driver.dialog(false);
}

Prevention

Know which backend (CDP vs WebDriver) each test targets before choosing dialog APIs
Never call onDialog in code shared across drivers without an instanceof guard
Prefer in-page (HTML) dialogs over native alert/confirm for portability

When it happens

Trigger: Calling driver.onDialog(handler) — or configuring Karate to set a dialog handler — while using a WebDriver-backed driver (geckodriver, safaridriver, or any W3C protocol driver) instead of a CDP-backed one.

Common situations: Code shared between Chrome (CDP) and Firefox (WebDriver) runs onDialog on both; users migrating tests from the CDP driver to a WebDriver backend; copy-pasted setup code enabling dialog auto-handling.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/64c80ec96719b641. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java:764

    // ========== Dialog (limited support) ==========

    @Override
    public Dialog getDialog() {
        try {
            String text = session.getAlertText();
            if (text != null) {
                return new W3cDialog(session, text);
            }
        } catch (Exception e) {
            // No alert present
        }
        return null;
    }

    @Override
    public void onDialog(DialogHandler handler) {
        throw new UnsupportedOperationException(
                "Dialog callback handler not supported on WebDriver backend. "
                        + "Use dialog(true/false) after the dialog appears.");
    }

    // ========== Navigation (abstract in Driver) ==========

    @Override
    public void setUrl(String url) {
        session.navigateTo(url);
    }

    @Override
    public void waitForPageLoad(PageLoadStrategy strategy) {
        // W3C handles page load internally - navigation commands are blocking
    }

    @Override
    public void waitForPageLoad(PageLoadStrategy strategy, java.time.Duration timeout) {

View on GitHub (pinned to a22eb90246)