karatelabs/karate · warning

doc() called, but no destination set

Error message

doc() called, but no destination set

What it means

karate.doc() in the JS engine logs this warning when invoked before any doc-rendering sink (onDoc callback) has been registered by the host runtime. In karate-core's KarateJs, the doc() invokable is always available in JS scope, but it only has a destination when an embed/reporting listener is attached (e.g. a UI or report renderer). Without one, the call is a no-op: a warning is logged and null is returned instead of throwing.

Solutions

1. Register a doc destination on the KarateJs instance before running (set the onDoc callback / use the standard runner that wires reporting).
2. Remove or guard the karate.doc(...) call if you do not need the rendered output in this run mode.
3. Check whether you are using a custom/embedded runner instead of the standard one; switch to the standard runner so the doc sink is configured automatically.
4. Treat the warning as benign if doc output is intentionally unsupported in this context — the call returns null safely.

Example fix

// before (custom runner, no doc sink)
KarateJs js = new KarateJs(context);
js.eval("karate.doc('some text')"); // warns: no destination set

// after — provide a destination
KarateJs js = new KarateJs(context);
js.onDoc(doc -> { log.info("doc: {}", doc); return null; });
js.eval("karate.doc('some text')");

// JS: check a marker set by your runner before using doc
if (typeof karate.doc === 'function') {
  karate.doc('report text');
}

function canDoc(karate) { return typeof karate.doc === 'function'; }

// doc() returns null instead of throwing; handle the null result
var rendered = karate.doc('text');
if (rendered === null) { /* doc sink not configured; skip or log */ }

When it happens

Trigger: Calling `karate.doc(...)` (or the `doc()` JS function) inside a scenario/JS block while running in a context where no onDoc callback was set on the KarateJs instance — e.g. headless/plain JVM embedding without a doc destination, or a custom runner that builds KarateJs directly and never registers a doc sink.

Common situations: Running V2 Karate via a custom embedded runner or test harness that did not wire up reporting; copying V1 feature code that used doc/embed-style output into an environment without a doc consumer; calling doc() from a background/JS utility where the reporting hook is not attached.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• embed() needs at least one argument: data
• embed(): each 'parts' entry must be an object
• embed(): each part needs a 'role'
• embed(): part ' ' needs 'data', 'path', or 'url
• read() needs at least one argument

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

Appendix: source

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

     * Called by the 'doc' keyword in StepExecutor.
     */
    public String doc(Map<String, Object> options) {
        String read = (String) options.get("read");
        if (read == null) {
            throw new RuntimeException("doc() requires 'read' key with template path");
        }
        String html = markup().processPath(read, null);
        if (onDoc != null) {
            onDoc.accept(html);
        }
        return html;
    }

    @SuppressWarnings("unchecked")
    private JavaInvokable doc() {
        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;

View on GitHub (pinned to a22eb90246)