karatelabs/karate · error · RuntimeException

missing 'mock' or 'handler' in intercept config

Error message

missing 'mock' or 'handler' in intercept config: {configMap}

What it means

The INTERCEPT callable in Driver.jsGet requires each intercept config to carry either a 'mock' (static response spec) or a 'handler' (function producing the response). When the config map has neither, the driver throws this RuntimeException embedding the config map. It is a config-shape validation so interception never silently no-ops.

Solutions

1. Provide a 'mock' for a canned response: { patterns: [...], mock: { status: 200, body: '...' } }
2. Or provide a 'handler' function that returns the response for dynamic mocking
3. Verify key spellings ('mock', 'handler', 'patterns') and inspect the echoed config map in the message for what actually arrived

Example fix

// before
driver.intercept({ patterns: ['https://x.com/*'], mocks: myMock });
// after
driver.intercept({ patterns: ['https://x.com/*'], mock: { status: 200, body: 'ok' } });

// JS: if (!cfg.mock && !cfg.handler) throw new Error('intercept needs mock or handler');

// JS: const hasResponse = cfg.mock != null || typeof cfg.handler === 'function';

try { driver.intercept(cfg); } catch (RuntimeException e) { if (e.getMessage().contains("missing 'mock' or 'handler'")) { /* fix config */ } else throw e; }

When it happens

Trigger: driver.intercept({ patterns: [...] }) with neither 'mock' nor 'handler' keys; keys misspelled ('mocks', 'respond'); the mock object built conditionally and ended up null/absent.

Common situations: Hand-written intercept configs copied from older examples; dynamically built configs where the mock/handler branch wasn't taken; typos after refactoring from 'mock' to a custom name.

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

• missing array argument 'patterns':
• driver keyword requires a URL argument
• driver URL evaluated to null:
• element not found:
• unknown window operation

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/driver/Driver.java:455

                            }
                            io.karatelabs.http.HttpResponse httpResponse = mockHandler.apply(httpRequest);
                            if (httpResponse != null) {
                                Map<String, Object> responseHeaders = new java.util.LinkedHashMap<>();
                                if (httpResponse.getHeaders() != null) {
                                    for (Map.Entry<String, List<String>> entry : httpResponse.getHeaders().entrySet()) {
                                        List<String> values = entry.getValue();
                                        if (values != null && !values.isEmpty()) {
                                            responseHeaders.put(entry.getKey(), values.getLast());
                                        }
                                    }
                                }
                                return InterceptResponse.of(httpResponse.getStatus(), responseHeaders,
                                        httpResponse.getBodyBytes() != null ? httpResponse.getBodyBytes() : new byte[0]);
                            }
                            return null;
                        });
                    } else {
                        throw new RuntimeException("missing 'mock' or 'handler' in intercept config: " + configMap);
                    }
                }
                return null;
            };

            // Dialog handling
            case DriverApi.DIALOG -> (JavaCallable) (ctx, args) -> {
                boolean accept = args.length > 0 && Boolean.TRUE.equals(args[0]);
                if (args.length > 1 && args[1] != null) {
                    dialog(accept, String.valueOf(args[1]));
                } else {
                    dialog(accept);
                }
                return null;
            };
            case DriverApi.ON_DIALOG -> (JavaCallable) (ctx, args) -> {
                if (args.length == 0 || args[0] == null) {
                    onDialog(null);

View on GitHub (pinned to a22eb90246)