{"record":{"id":"d4c019748b2025ef","repo":"karatelabs/karate","slug":"tab-index-out-of-bounds-index-available-handles-size","errorCode":null,"errorMessage":"Tab index out of bounds: ${index} (available: ${handles.size()})","messagePattern":"Tab index out of bounds: (.+?) \\(available: (.+?)\\)","errorType":"exception","errorClass":"DriverException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java","lineNumber":340,"sourceCode":"    @Override\n    public void window(String operation) {\n        switch (operation) {\n            case \"maximize\" -> session.maximizeWindow();\n            case \"minimize\" -> session.minimizeWindow();\n            case \"fullscreen\" -> session.fullscreenWindow();\n            default -> logger.warn(\"Unknown window operation: {}\", operation);\n        }\n    }\n\n    @Override\n    public void tab(Object target) {\n        if (target instanceof Integer) {\n            List<String> handles = session.getWindowHandles();\n            int index = (Integer) target;\n            if (index >= 0 && index < handles.size()) {\n                session.switchWindow(handles.get(index));\n            } else {\n                throw new DriverException(\"Tab index out of bounds: \" + index\n                        + \" (available: \" + handles.size() + \")\");\n            }\n        } else if (target instanceof String) {\n            String titleOrUrl = (String) target;\n            String currentHandle = session.getWindowHandle();\n            List<String> handles = session.getWindowHandles();\n            for (String handle : handles) {\n                session.switchWindow(handle);\n                String title = session.getTitle();\n                String url = session.getUrl();\n                if ((title != null && title.contains(titleOrUrl))\n                        || (url != null && url.contains(titleOrUrl))) {\n                    return; // Found it\n                }\n            }\n            // Not found, restore original\n            session.switchWindow(currentHandle);\n            throw new DriverException(\"No tab found matching: \" + titleOrUrl);","sourceCodeStart":322,"sourceCodeEnd":358,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/driver/w3c/W3cDriver.java#L322-L358","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check session.getWindowHandles().size() (or the count in the error) before switching","Use a valid 0-based index, or switch by title/URL string instead","Ensure the new tab/popup actually opened (wait for the handle count to increase) before indexing","Re-count tabs after any close/navigation in the test flow"],"exampleFix":"// before\ntab(1); // assumes popup opened\n// after\nif (driver.windowHandles().size() > 1) { tab(1); }","handlingStrategy":"type-guard","validationCode":"int handles = driver.windowHandles().size();\nif (index >= 0 && index < handles) {\n    driver.tab(index);\n}","typeGuard":"boolean tabExists(int index, W3cDriver d) {\n    return index >= 0 && index < d.windowHandles().size();\n}","tryCatchPattern":"try {\n    driver.tab(index);\n} catch (DriverException e) {\n    if (e.getMessage().startsWith(\"Tab index out of bounds\")) {\n        // handle count changed; re-evaluate and retry\n        int n = driver.windowHandles().size();\n        if (n > 0) driver.tab(Math.min(index, n - 1));\n    } else throw e;\n}","preventionTips":["Wait for the new tab/popup handle to appear before switching","Remember indices are 0-based","Recount handles after any tab close/navigation","Prefer switching by URL substring when order is unpredictable"],"tags":["tab","index-out-of-bounds","webdriver","window-handling"],"backgroundTag":"index-out-of-bounds","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}