karatelabs/karate · error · RuntimeException

sysenv() needs the environment-variable name

Error message

sysenv() needs the environment-variable name

What it means

karate.sysenv() reads an OS environment variable and supports an optional fallback; the environment-variable name is mandatory. Karate throws this when called with zero arguments because there is no name to look up in System.getenv().

Solutions

1. Pass the variable name: karate.sysenv('MY_ENV_VAR').
2. Use the fallback form karate.sysenv('MY_ENV_VAR', 'default') to avoid null/empty results.
3. Check karate-config.js for calls where the name argument was lost.

Example fix

// before
var token = karate.sysenv();
// after
var token = karate.sysenv('API_TOKEN', 'dev-default');

if (!envName) throw new Error('sysenv requires a variable name');
var v = karate.sysenv(envName, fallback);

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

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

When it happens

Trigger: Calling karate.sysenv() with no arguments; forgetting the name when using the fallback form karate.sysenv('FOO', 'default') so only the fallback remains.

Common situations: Configuring environment-driven values in karate-config.js and accidentally omitting the variable name; refactoring that removed the first argument but kept the default.

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
• sysprop() needs the property 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/9b6b57fc1c8c804d. Report an issue: GitHub.

Appendix: source

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

        };
    }

    /**
     * Read a file as raw bytes. Useful for binary content handling.
     * Usage: karate.readAsBytes('path/to/file')
     */
    /**
     * {@code karate.sysenv('NAME')} / {@code karate.sysenv('NAME', 'default')} —
     * read an OS environment variable. Returns the value as a String. When the
     * variable is unset or empty, returns the optional second argument (or
     * {@code null} when no default is supplied) — matches shell {@code ${VAR:-default}}
     * semantics so the previous {@code karate.sysenv('FOO') || 'default'} idiom
     * collapses to a single call.
     */
    private JavaInvokable sysenv() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("sysenv() needs the environment-variable name");
            }
            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) {

View on GitHub (pinned to a22eb90246)