karatelabs/karate · error · RuntimeException

read() requires a path argument

Error message

read() requires a path argument

What it means

MarkupContext exposes a JS-callable `read(path)` function to load template/resource content by path. When it is invoked with no arguments or with null as the first argument, the JavaInvokable wrapper throws this RuntimeException because there is no path to resolve.

Solutions

1. Pass an explicit path string: `context.read('/fragments/header.html')`.
2. If the path comes from a variable, guard it: only call read when the variable is present, or supply a default (`someVar ?: '/fragments/header.html'`).
3. Check the model/scope for the key feeding the path — a missing model value is usually the root cause.
4. If the intent was optional inclusion, wrap the call in a condition rather than passing null.

Example fix

// before
var content = context.read(pathOrNull);

// after
var content = pathOrNull != null ? context.read(pathOrNull) : '';

function safeRead(ctx, path) {
  if (path == null || path === '') return null;
  return ctx.read(path);
}

function hasPath(a) { return a != null && typeof a === 'string' && a.length > 0; }
// usage: if (hasPath(p)) context.read(p);

try {
  var content = context.read(p);
} catch (e) {
  if (e.message === 'read() requires a path argument') {
    content = '';
  } else { throw e; }
}

When it happens

Trigger: Calling `context.read()` or `context.read(null)` inside a template script/expression where the path argument is missing or evaluates to null.

Common situations: A template variable holding the path is undefined/null at render time (e.g. `context.read(someVar)` with an unset model key); forgetting the argument when converting an inline include to `read()`; conditional template paths that resolve to null.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• readBytes() requires a path argument
• toJson() requires an object argument
• fromJson() requires a JSON string argument
• context.get() requires a name argument
• karate-markup does not support param lists in th:fragment…

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/markup/MarkupContext.java:127

     * Default returns null; implementations override to surface the scope
     * to the {@code context.get} dispatch path.
     */
    default MarkupScope getMarkupScope() {
        return null;
    }

    /**
     * Default implementation of jsGet that exposes context methods to JavaScript.
     * Implementations can override to add more properties/methods.
     */
    @Override
    default Object jsGet(String key) {
        return switch (key) {
            case "template" -> getTemplateName();
            case "caller" -> getCallerTemplateName();
            case "read" -> (JavaInvokable) args -> {
                if (args.length == 0 || args[0] == null) {
                    throw new RuntimeException("read() requires a path argument");
                }
                return read(args[0].toString());
            };
            case "readBytes" -> (JavaInvokable) args -> {
                if (args.length == 0 || args[0] == null) {
                    throw new RuntimeException("readBytes() requires a path argument");
                }
                return readBytes(args[0].toString());
            };
            case "toJson" -> (JavaInvokable) args -> {
                // null IS a valid JSON-able value (`null`), so only the
                // missing-arg case errors here.
                if (args.length == 0) throw new RuntimeException("toJson() requires an object argument");
                return toJson(args[0]);
            };
            case "fromJson" -> (JavaInvokable) args -> {
                if (args.length == 0 || args[0] == null) {
                    throw new RuntimeException("fromJson() requires a JSON string argument");

View on GitHub (pinned to a22eb90246)