karatelabs/karate · error · DriverException

Tab index out of bounds

Error message

Tab index out of bounds: ${index} (available: ${handles.size()})

What it means

W3cDriver.tab(target) with an Integer target switches to the window handle at that index. If the index is negative or >= the number of open window handles, it throws DriverException 'Tab index out of bounds: <index> (available: <n>)'. The message includes the count of actually open tabs/handles.

Solutions

1. Check session.getWindowHandles().size() (or the count in the error) before switching
2. Use a valid 0-based index, or switch by title/URL string instead
3. Ensure the new tab/popup actually opened (wait for the handle count to increase) before indexing
4. Re-count tabs after any close/navigation in the test flow

Example fix

// before
tab(1); // assumes popup opened
// after
if (driver.windowHandles().size() > 1) { tab(1); }

int handles = driver.windowHandles().size();
if (index >= 0 && index < handles) {
    driver.tab(index);
}

boolean tabExists(int index, W3cDriver d) {
    return index >= 0 && index < d.windowHandles().size();
}

try {
    driver.tab(index);
} catch (DriverException e) {
    if (e.getMessage().startsWith("Tab index out of bounds")) {
        // handle count changed; re-evaluate and retry
        int n = driver.windowHandles().size();
        if (n > 0) driver.tab(Math.min(index, n - 1));
    } else throw e;
}

When it happens

Trigger: Calling tab(2) when only 2 tabs exist (valid indices 0..1); calling tab(n) after a popup/tab was closed, shrinking the handle list; assuming a tab opened when window handling failed.

Common situations: Popup blocked by the browser so the expected new tab never opened; tab closed by site or user code before switching; off-by-one from 1-based thinking; tests running in fresh browser contexts with fewer tabs than dev-machine assumptions.

Related errors

• No tab found matching
• no page at index
• Could not find active element for keyboard input
• Dialog callback handler not supported on WebDriver backend…
• Element not found

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

Appendix: source

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

    @Override
    public void window(String operation) {
        switch (operation) {
            case "maximize" -> session.maximizeWindow();
            case "minimize" -> session.minimizeWindow();
            case "fullscreen" -> session.fullscreenWindow();
            default -> logger.warn("Unknown window operation: {}", operation);
        }
    }

    @Override
    public void tab(Object target) {
        if (target instanceof Integer) {
            List<String> handles = session.getWindowHandles();
            int index = (Integer) target;
            if (index >= 0 && index < handles.size()) {
                session.switchWindow(handles.get(index));
            } else {
                throw new DriverException("Tab index out of bounds: " + index
                        + " (available: " + handles.size() + ")");
            }
        } else if (target instanceof String) {
            String titleOrUrl = (String) target;
            String currentHandle = session.getWindowHandle();
            List<String> handles = session.getWindowHandles();
            for (String handle : handles) {
                session.switchWindow(handle);
                String title = session.getTitle();
                String url = session.getUrl();
                if ((title != null && title.contains(titleOrUrl))
                        || (url != null && url.contains(titleOrUrl))) {
                    return; // Found it
                }
            }
            // Not found, restore original
            session.switchWindow(currentHandle);
            throw new DriverException("No tab found matching: " + titleOrUrl);

View on GitHub (pinned to a22eb90246)