karatelabs/karate · error · RuntimeException

start() config requires 'mock' key with feature path

Error message

start() config requires 'mock' key with feature path

What it means

When `karate.start()` receives a Map, the library treats it as a mock-server config and requires a `mock` key holding the feature file path. A Map without `mock` gives the server nothing to mount, so it throws this error telling you exactly which key is required.

Solutions

1. Add the required key: karate.start({ mock: 'api.feature' })
2. Fix key misspellings — the key must be exactly 'mock'
3. If you meant to start a real server rather than a mock, use karate.fork()/karate.exec() instead
4. Assert the config before calling: if (!config.mock) throw 'mock path missing'

Example fix

// before
karate.start({ feature: 'api.feature', port: 8080 }) // wrong key
// after
karate.start({ mock: 'api.feature', port: 8080 })

// JS
if (cfg && !cfg.mock) throw new Error('config map to karate.start() must include mock: <feature path>');
karate.start(cfg);

function isStartConfig(cfg) { return cfg !== null && typeof cfg === 'object' && typeof cfg.mock === 'string' && cfg.mock.length > 0; }

try { var server = karate.start(cfg); } catch (e) { if (('' + e).indexOf("'mock' key") !== -1) { karate.log('config missing mock key, keys=' + Object.keys(cfg)); } throw e; }

When it happens

Trigger: karate.start({ port: 8080 }) or karate.start({ features: [...], ssl: true }) — any config Map whose `mock` key is absent or null (e.g. config.get("mock") returns null because the key is misspelled as 'feature', 'mocks', or 'path').

Common situations: Misspelling the key ('mocks', 'feature', 'file'); copying a config from karate-config style objects where the feature key is named differently; building the config programmatically and forgetting to set mock; using a real HTTP mock config from a different tool with different key names.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• start() needs at least one argument: feature path or config…
• start() argument must be a string path or config map
• proceed() can only be called within a mock scenario
• proceed() needs a target URL or Host header in request
• scenario match evaluation failed at line

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

Appendix: source

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

     */
    @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());
                }
                if (config.containsKey("ssl")) {
                    builder.ssl(Boolean.TRUE.equals(config.get("ssl")));
                }
                if (config.containsKey("cert")) {
                    builder.certPath((String) config.get("cert"));
                }
                if (config.containsKey("key")) {
                    builder.keyPath((String) config.get("key"));
                }
                if (config.containsKey("arg")) {
                    builder.arg((Map<String, Object>) config.get("arg"));
                }

View on GitHub (pinned to a22eb90246)