karatelabs/karate · error · RuntimeException

doc() read arg should not be null

Error message

doc() read arg should not be null

What it means

After extracting the 'read' value from doc()'s first argument (map, null, or string-coerced value), Karate requires it to be non-null. An explicit null — e.g. doc(null) or doc({ read: null }) — throws this error since there is no template to render.

Solutions

1. Verify the variable holding the template path is set before calling doc()
2. Default the path: read = path || 'classpath:doc/default.html'
3. Check the config/env map key that supplies the path for typos

Example fix

// before
* doc({ read: docPath })   // docPath is undefined in this env
// after
* def docPath = karate.env == 'dev' ? 'classpath:doc/dev.html' : 'classpath:doc/default.html'
* doc({ read: docPath })

if (readPath == null) { readPath = 'classpath:doc/default.html'; }

function isNonEmptyString(v) { return typeof v === 'string' && v.length > 0; }

try { karate.doc(readPath); } catch (RuntimeException e) { if (e.getMessage().contains('read arg should not be null')) { log.error('template path variable is null — check env config'); } throw e; }

When it happens

Trigger: Calling karate.doc(null), or doc({ read: someVar }) where someVar is null/undefined; a config or variable that should hold a path but was never set.

Common situations: Environment-specific path variables not initialized for the active environment; reading the path from a config map with a misspelled key; conditional logic that skips assigning the template path.

Related errors

• doc() requires 'read' key with template path
• doc() needs at least one argument
• switch() requires a template argument
• Unable to resolve global `this`
• Invalid ignore

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJs.java:183

        return args -> {
            if (onDoc == null) {
                logger.warn("doc() called, but no destination set");
                return null;
            }
            if (args.length == 0) {
                throw new RuntimeException("doc() needs at least one argument");
            }
            String read;
            if (args[0] instanceof Map) {
                Map<String, Object> map = (Map<String, Object>) args[0];
                read = (String) map.get("read");
            } else if (args[0] == null) {
                read = null;
            } else {
                read = args[0] + "";
            }
            if (read == null) {
                throw new RuntimeException("doc() read arg should not be null");
            }
            Map<String, Object> vars;
            if (args.length > 1) {
                vars = (Map<String, Object>) args[1];
            } else {
                vars = null;
            }
            String html = markup().processPath(read, vars);
            onDoc.accept(html);
            return null;
        };
    }

    // ========== Engine-Dependent Methods ==========
    // These methods require access to the JavaScript engine for evaluation.

    private JavaCallable initRead() {
        return (context, args) -> {

View on GitHub (pinned to a22eb90246)