karatelabs/karate · error · RuntimeException

fork() needs at least one argument

Error message

fork() needs at least one argument

What it means

Karate's JS `karate.fork()` spawns a background OS process and needs the command to run. Called with zero arguments there is nothing to fork, so the library throws immediately instead of returning a useless ProcessHandle.

Solutions

  1. Pass at least one argument: karate.fork('server.js') or karate.fork(['node', 'server.js'])
  2. If building args dynamically, validate the array is non-empty before calling: if (args.length) karate.fork(args)
  3. Pass an options Map with the command: karate.fork({ args: [...], listen: true })
  4. Check for typos where the command variable resolves to empty at call time

Example fix

// before
var cmd = []; // built dynamically, ended up empty
karate.fork() // throws
// after
if (cmd.length === 0) karate.fail('no command to fork');
karate.fork(cmd);
Defensive patterns

Strategy: validation

Validate before calling

// JS
if (!cmd || (Array.isArray(cmd) && cmd.length === 0)) throw new Error('fork command missing');
karate.fork(cmd);

Try / catch

try { var h = karate.fork(cmd); } catch (e) { if (('' + e).indexOf('fork() needs at least one argument') !== -1) { karate.log('fork called with no command'); } throw e; }

Prevention

When it happens

Trigger: Calling karate.fork() with no arguments at all, or with only trailing/optional-style arguments that all evaluate such that args.length == 0 (e.g. karate.fork.apply([]) style invocation or a spread of an empty array).

Common situations: Building the argument dynamically from a variable that is empty/undefined so the call site effectively passes nothing; refactor that dropped the argument; assuming fork() with no args starts a default shell like some other tools do.

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

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

Appendix: source

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

    /**
     * karate.fork() - Asynchronous process execution.
     * Returns ProcessHandle for async control.
     * Usage:
     * var proc = karate.fork('ping google.com')
     * var proc = karate.fork({ args: ['node', 'server.js'], listener: fn })
     * var proc = karate.fork({ args: [...], start: false })  // deferred start
     * proc.onStdOut(fn).start()
     * proc.waitSync()
     * proc.stdOut
     * proc.exitCode
     * proc.close()
     */
    @SuppressWarnings("unchecked")
    private JavaInvokable fork() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("fork() needs at least one argument");
            }
            ProcessBuilder builder = ProcessBuilder.create();
            Consumer<String> listener = null;
            Consumer<String> errorListener = null;
            boolean autoStart = true;

            Object arg = args[0];
            if (arg instanceof String) {
                builder.line((String) arg);
            } else if (arg instanceof List) {
                builder.args((List<String>) arg);
            } else if (arg instanceof Map) {
                Map<String, Object> options = (Map<String, Object>) arg;
                builder = ProcessBuilder.fromMap(options);

                // Extract listener function (receives line string directly)
                Object listenerObj = options.get("listener");
                if (listenerObj instanceof JavaCallable jsListener) {

View on GitHub (pinned to a22eb90246)