karatelabs/karate · error · RuntimeException

missing argument for files()

Error message

missing argument for files()

What it means

HttpRequest.files() is a script-facing invokable that takes one argument (a JSON/map of part names to file paths) and forwards it to getFiles(). Called with zero arguments it throws this RuntimeException to fail fast rather than returning null parts.

Solutions

1. Pass the JSON map of parts: request.files(read('files.json'))
2. Ensure the map variable is defined and non-empty before the call
3. For a single file use file(); for a single form field use multiPart()
4. If directory-wildcard attachment was intended, build the map yourself (e.g. via karate.forEach over a listing) and pass it

Example fix

// before
request.files(); // throws
// after
request.files({ file1: "a.txt", file2: "b.txt" });

if (filesMap == null || Object.keys(filesMap).length === 0) throw new Error('files() needs a non-empty map of name -> path');
request.files(filesMap);

function isNonEmptyMap(v) { return v != null && typeof v === 'object' && Object.keys(v).length > 0; }

When it happens

Trigger: Calling files() with no arguments, e.g. request.files() instead of request.files({ a: 'a.txt', b: 'b.txt' }); passing an object but through a binding that loses the argument; confusing files() with a no-arg 'list files' getter.

Common situations: Bulk multi-file uploads driven by dynamic maps that were never populated; refactors that renamed a variable leaving the call empty; users assuming files() with no args attaches all files in a directory.

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

• missing argument for file()
• missing argument for multiPart()
• cache() requires (key, fn)
• header() needs two arguments
• param() needs two arguments

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/HttpRequest.java:695

        };
    }

    private JavaInvokable file() {
        return args -> {
            if (args.length > 0) {
                return getFile(args[0] + "");
            } else {
                throw new RuntimeException("missing argument for file()");
            }
        };
    }

    private JavaInvokable files() {
        return args -> {
            if (args.length > 0) {
                return getFiles(args[0] + "");
            } else {
                throw new RuntimeException("missing argument for files()");
            }
        };
    }

    /**
     * Forward this request to a target URL and return the response.
     * Mirrors {@code karate.proceed()} so JS-file mocks can implement proxy behavior.
     * If {@code targetUrl} is null, uses the {@code Host} header on this request.
     */
    public HttpResponse proceed(String targetUrl) {
        if (targetUrl == null) {
            String host = getHeader("Host");
            if (host == null) {
                throw new RuntimeException("proceed() needs a target URL or Host header in request");
            }
            targetUrl = "http://" + host;
        }
        HttpClient client = httpClient != null ? httpClient : new DefaultHttpClientFactory().create();

View on GitHub (pinned to a22eb90246)