karatelabs/karate · critical · RuntimeException

Failed to load

Error message

Failed to load {name}

What it means

CdpDriver statically loads its bundled driver.js init script from the classpath (/io/karatelabs/driver/driver.js). If the resource stream is null or reading fails, loadResource throws 'Failed to load driver.js'. This is a packaging/classpath corruption problem, not a runtime behavior issue.

Solutions

  1. Delete the karate-core artifact from the local Maven repo and re-download (mvn -U)
  2. Verify the jar contains io/karatelabs/driver/driver.js (unzip -l)
  3. Use the official published karate-core artifact instead of a custom shaded/relocated build
  4. Check the packaging config of any fat jar keeps /io/karatelabs/driver/ resources

Example fix

// before: corrupted jar
ls ~/.m2/repository/io/karatelabs/karate-core/.../karate-core.jar # truncated
// after
rm -rf ~/.m2/repository/io/karatelabs/karate-core
mvn -U clean test
Defensive patterns

Strategy: validation

Validate before calling

// pre-check the resource exists before any CdpDriver use
java.io.InputStream is = CdpDriver.class
    .getResourceAsStream("/io/karatelabs/driver/driver.js");
if (is == null) {
    throw new IllegalStateException("karate-core jar missing driver.js — re-download dependencies");
}
is.close();

Type guard

null

Try / catch

try { Driver d = karate.driver; }
catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Failed to load ")) {
        throw new IllegalStateException("Corrupt karate-core jar; run mvn -U after clearing the cache", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: karate-core jar is truncated or corrupted in the local Maven cache; a shaded/fat jar excludes the resource; custom classloader that cannot see the karate-core resources; build/packaging misconfiguration dropping resources.

Common situations: Corrupted ~/.m2 cache after a failed download; running with a repackaged jar missing resources; IDE/dependency conflicts pulling a broken karate-core artifact; Docker images that strip resources.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;

/**
 * CDP-based browser driver implementation.
 * Implements the Driver interface using Chrome DevTools Protocol.
 */
public class CdpDriver implements Driver {

    private static final Logger logger = LogContext.RUNTIME_LOGGER;

    // Karate JS runtime (wildcard resolver, shared utilities)
    private static final String DRIVER_JS = loadResource("driver.js");

    private static String loadResource(String name) {
        try (InputStream is = CdpDriver.class.getResourceAsStream("/io/karatelabs/driver/" + name)) {
            return new String(is.readAllBytes(), StandardCharsets.UTF_8);
        } catch (Exception e) {
            throw new RuntimeException("Failed to load " + name, e);
        }
    }

    // Track active drivers for cleanup
    private static final Set<CdpDriver> ACTIVE = ConcurrentHashMap.newKeySet();

    private final CdpClient cdp;
    private final CdpDriverOptions options;
    private final CdpLauncher launcher; // null if connected to existing browser

    // Page load state
    private volatile boolean domContentEventFired;
    private final Set<String> framesStillLoading = ConcurrentHashMap.newKeySet();
    // volatile: written on the scenario thread (initialize / activateTarget), read by
    // every Page.* event handler on the CDP dispatch thread for main-frame filtering
    private volatile String mainFrameId;
    private volatile String pendingNavigationUrl; // for better timeout diagnostics

View on GitHub (pinned to a22eb90246)