karatelabs/karate · error · DriverException

targetId is null

Error message

targetId is null

What it means

CdpDriver.switchPageById(targetId) rejects a null targetId outright with this DriverException before doing any CDP work. It exists to fail fast on a null handle — typically the result of a previously failed lookup — instead of throwing an obscure NPE deep in CDP messaging.

Solutions

1. Null-check or assert the targetId before calling switchPageById
2. Fix the upstream lookup that produced null (usually error 236's 'no page found matching' path)
3. If id may legitimately be missing, use a guarded switch that skips or reports instead of forwarding null

Example fix

// before
driver.switchPageById(targetIdFromSomewhere); // may be null
// after
if (targetIdFromSomewhere != null) {
    driver.switchPageById(targetIdFromSomewhere);
} else {
    throw new IllegalStateException("no targetId captured from prior step");
}

if (targetId == null || targetId.isBlank()) {
    throw new IllegalArgumentException("switchPageById requires a non-null targetId");
}
driver.switchPageById(targetId);

try {
    driver.switchPageById(targetId);
} catch (DriverException e) {
    if (e.getMessage().contains("targetId is null")) {
        throw new IllegalStateException("targetId was never captured from the prior step", e);
    }
    throw e;
}

When it happens

Trigger: Passing null to switchPageById, most often because a prior call (findPageTarget, drainOpenedTargets, a stored target id variable) returned null and was forwarded unchecked.

Common situations: Chaining switchPageById(resultOfLookup) where the lookup timed out earlier; a Java variable holding the target id never assigned; test data/JSON missing the targetId field.

Related errors

• no page at index
• no page found matching
• no page found with targetId
• bad wildcard locator
• boot.classpath: dir is null — pass a project-relative…

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/cdp/CdpDriver.java:3987

            String title = (String) target.get("title");
            String url = (String) target.get("url");
            if ((title != null && title.contains(titleOrUrl)) ||
                    (url != null && url.contains(titleOrUrl))) {
                return (String) target.get("targetId");
            }
        }
        return null;
    }

    /**
     * Switch to a page by its backend target ID (unambiguous — avoids URL/title
     * collisions that {@link #switchPage(String)} is vulnerable to).
     */
    @Override
    public void switchPageById(String targetId) {
        logger.debug("switch page by targetId: {}", targetId);
        if (targetId == null) {
            throw new DriverException("targetId is null");
        }
        // Verify the target exists as a page target before activating, retrying within
        // the auto-wait budget: Target.getTargets can briefly lag a freshly opened tab.
        int interval = fastPollInterval();
        int maxAttempts = fastPollAttempts();
        for (int attempt = 0; ; attempt++) {
            if (getPages().contains(targetId)) {
                activateTarget(targetId);
                return;
            }
            if (attempt >= maxAttempts) {
                break;
            }
            sleep(interval);
        }
        throw new DriverException("no page found with targetId: " + targetId);
    }

View on GitHub (pinned to a22eb90246)