karatelabs/karate · error · DriverException

init script ' ' depends on unregistered

Error message

init script '{name}' depends on unregistered '{dep}'

What it means

CdpDriver.addInitScript(name, fn, deps) requires all dependency init scripts to be registered before a script that declares them. If a listed dep is missing from initScripts, it throws DriverException 'init script "<name>" depends on unregistered "<dep>"'. This enforces registration order for scripts injected into every new document.

Solutions

  1. Register the dependency script first (call addInitScript for the dep before the dependent script)
  2. Check the deps array spelling against registered script names
  3. If depending on Karate's built-in runtime, note DRIVER_JS is installed automatically — don't list it as an unregistered dep
  4. Reorder initialization so dependencies precede dependents in your setup/config code

Example fix

// before: dep not registered
karate.driver.addInitScript("myscript", myFn, new String[]{"base-utils"}); // base-utils never added
// after: register dep first
karate.driver.addInitScript("base-utils", baseUtilsFn);
karate.driver.addInitScript("myscript", myFn, new String[]{"base-utils"});
Defensive patterns

Strategy: validation

Validate before calling

// before adding a dependent script, verify deps registered
Set<String> registered = getRegisteredInitScriptNames(); // your own tracking
for (String dep : deps) {
    if (!registered.contains(dep)) {
        throw new IllegalStateException("register dep first: " + dep);
    }
}

Type guard

null

Try / catch

try { driver.addInitScript("name", fn, deps); }
catch (DriverException e) {
    if (e.getMessage().contains("depends on unregistered")) {
        registerMissingDeps(deps); // add deps, then retry once
        driver.addInitScript("name", fn, deps);
    } else throw e;
}

Prevention

When it happens

Trigger: Calling addInitScript with a deps array naming a script never registered (or registered later); custom init scripts depending on built-in modules without registering/adding them first; renaming/removing a built-in dependency script in a newer version.

Common situations: Users adding custom init scripts on top of Karate's built-ins but omitting the required base dependency; copy-pasted setup code referencing a dep that was never added; upgrading Karate where an internal script name changed.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

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

     * registered it stays injected lazily on demand, so the default page footprint is unchanged.
     * <p>
     * Idempotent by {@code name} — a second call for an already-registered name is a no-op (so a
     * module may carry its own re-entry guard and be safely re-evaluated on each navigation).
     * Pair with {@link #removeInitScript(String)}.
     *
     * @param name   a stable identifier for the module
     * @param source the JavaScript source
     * @param deps   names of already-registered modules that must run before this one
     * @throws DriverException if a declared dependency has not been registered
     */
    public void addInitScript(String name, String source, String... deps) {
        synchronized (initScriptLock) {
            if (initScripts.containsKey(name)) {
                return;
            }
            for (String dep : deps) {
                if (!initScripts.containsKey(dep)) {
                    throw new DriverException("init script '" + name + "' depends on unregistered '" + dep + "'");
                }
            }
            // install the built-in runtime first so every module can rely on its window utilities
            if (runtimeInitId == null) {
                runtimeInitId = addScriptToEvaluateOnNewDocument(DRIVER_JS);
            }
            String cdpId = addScriptToEvaluateOnNewDocument(source);
            initScripts.put(name, new InitScript(source, List.of(deps), cdpId));
            // new-document installs fire on the NEXT document — also inject into the current one
            try {
                ensureKjsRuntime();
                evalDirect(source);
            } catch (Exception e) {
                logger.debug("init script '{}' inject into current document deferred: {}", name, e.getMessage());
            }
        }
    }

View on GitHub (pinned to a22eb90246)