karatelabs/karate · error · RuntimeException

sysprop() needs the property name

Error message

sysprop() needs the property name

What it means

karate.sysprop() reads a JVM system property (from CLI -D, Maven/Gradle, or Runner.Builder.systemProperties) with optional fallback; the property name is required. Karate throws this when the callable receives zero arguments.

Solutions

1. Pass the property name: karate.sysprop('karate.env').
2. Use karate.sysprop('prop.name', 'fallback') for defaults.
3. Verify the property name is a non-empty string literal or defined variable.

Example fix

// before
var env = karate.sysprop();
// after
var env = karate.sysprop('karate.env', 'dev');

if (!propName) throw new Error('sysprop requires a property name');
var v = karate.sysprop(propName, fallback);

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

var v;
try { v = karate.sysprop(name, 'default'); }
catch (e) { if ((e.message || '').indexOf('sysprop() needs') >= 0) v = 'default'; else throw e; }

When it happens

Trigger: Calling karate.sysenv()/sysprop() incorrectly, specifically karate.sysprop() with an empty args list; omitting the name when using the two-argument default form.

Common situations: Wiring runner-configurable properties in karate-config.js and dropping the name argument during refactor; copy-paste of sysprop lines where the string literal was deleted.

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

• read() needs at least one argument
• sysenv() needs the environment-variable name
• readAsBytes() needs at least one argument
• get() needs at least one argument
• set() with a single argument expects a Map / JSON object

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

Appendix: source

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

            }
            Object fallback = args.length > 1 ? args[1] : null;
            Object first = args[0];
            if (first == null) return fallback;
            String value = System.getenv(first.toString());
            return (value == null || value.isEmpty()) ? fallback : value;
        };
    }

    /**
     * {@code karate.sysprop('NAME')} / {@code karate.sysprop('NAME', 'default')} —
     * read a JVM system property. Cleaner alternative to
     * {@code karate.properties['NAME']} with first-class default support; reads
     * from the same merged map (CLI {@code -D}, Maven/Gradle, and {@code Runner.Builder.systemProperties}).
     */
    private JavaInvokable sysprop() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("sysprop() needs the property name");
            }
            Object fallback = args.length > 1 ? args[1] : null;
            Object first = args[0];
            if (first == null) return fallback;
            String value = getProperty(first.toString());
            return (value == null || value.isEmpty()) ? fallback : value;
        };
    }

    private JavaInvokable readAsBytes() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("readAsBytes() needs at least one argument");
            }
            String path = args[0] + "";
            Resource resource = getCurrentResource().resolve(path);
            try (java.io.InputStream is = resource.getStream()) {
                return is.readAllBytes();

View on GitHub (pinned to a22eb90246)