karatelabs/karate · error · RuntimeException

start() needs at least one argument: feature path or config…

Error message

start() needs at least one argument: feature path or config map

What it means

`karate.start()` launches a Karate mock server and requires either a feature file path (String) or a config Map (e.g. { mock: 'api.feature', port: 8080 }). With zero arguments there is no feature to serve, so the library throws this descriptive error naming both accepted forms.

Solutions

Pass the feature path: karate.start('classpath:mocks/api.feature') or karate.start('api.feature') relative to the script root
Pass a config Map: karate.start({ mock: 'api.feature', port: 8080 })
If the path is dynamic, ensure it resolves to a non-empty value before calling
Verify you are not confusing start() with an argument-less lifecycle hook from another API

Example fix

// before
karate.start() // throws
// after
var server = karate.start({ mock: 'animals-mock.feature', port: 8080 });

Defensive patterns

Strategy: validation

Validate before calling

// JS
if (typeof featureOrConfig === 'undefined' || featureOrConfig === null) throw new Error('karate.start() requires a feature path or config map');
var server = karate.start(featureOrConfig);

Type guard

function isStartArg(v) { return typeof v === 'string' || (v !== null && typeof v === 'object'); }

Try / catch

try { var server = karate.start(cfg); } catch (e) { if (('' + e).indexOf('start() needs at least one argument') !== -1) { karate.log('start() called without feature path or config'); } throw e; }

Prevention

Always pass a feature path or { mock: ... } map
Check dynamic path variables resolve before calling
Do not confuse start() with argument-less lifecycle hooks

When it happens

Trigger: Calling karate.start() with no arguments, or an invocation where all arguments were dropped (spread of empty array, apply with empty args list).

Common situations: Refactoring that removed the feature path; assuming start() picks up a default config file like karate-config.js does; dynamically resolved path variable left undefined so the call effectively passes nothing; confusing karate.start() with karate.setup() or a background hook that takes no args.

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/c9d3640c12d6a364. Report an issue: GitHub.

Appendix: source

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

            }
            return handle;
        };
    }

    /**
     * karate.start() - Start a mock server from a feature file.
     * Usage:
     * <pre>
     * var server = karate.start('api.feature');
     * var server = karate.start({ mock: 'api.feature', port: 8080 });
     * var server = karate.start({ mock: 'api.feature', port: 8443, ssl: true });
     * </pre>
     */
    @SuppressWarnings("unchecked")
    private JavaInvokable start() {
        return args -> {
            if (args.length == 0) {
                throw new RuntimeException("start() needs at least one argument: feature path or config map");
            }
            Object arg = args[0];
            MockServer.Builder builder;

            if (arg instanceof String path) {
                // Simple path: karate.start('api.feature')
                builder = MockServer.feature(root.resolve(path));
            } else if (arg instanceof Map) {
                // Config map: karate.start({ mock: 'api.feature', port: 8080 })
                Map<String, Object> config = (Map<String, Object>) arg;
                String mockPath = (String) config.get("mock");
                if (mockPath == null) {
                    throw new RuntimeException("start() config requires 'mock' key with feature path");
                }
                builder = MockServer.feature(root.resolve(mockPath));

                if (config.containsKey("port")) {
                    builder.port(((Number) config.get("port")).intValue());

View on GitHub (pinned to a22eb90246)