karatelabs/karate · error · RuntimeException

unknown keyword

Error message

unknown keyword: <keyword>

What it means

Karate could not match the first word of a step line to any known Gherkin keyword (Given/When/Then/And/But, def, call, eval, method, etc.). If the remaining text starts with '(' the keyword is treated as a function-call name and evaluated (e.g. myFunc('a')); otherwise this RuntimeException is thrown because the line is not a valid step.

Solutions

1. Fix the first word of the step to a valid keyword (Given, When, Then, And, But, def, call, eval, print, method, match, assert, etc.)
2. If you intended a function call, prefix the expression so the line is a valid 'def' or use 'eval myFunc(...)'
3. Check the feature file for mixed-language keywords if running non-English features
4. If building Step objects in code, verify the keyword string matches Karate's keyword set exactly (case-sensitive)

Example fix

// before (feature)
Def x = 5
whenn url == '/foo'
// after
def x = 5
When url == '/foo'

// check the step keyword before executing
java.util.Set<String> known = java.util.Set.of("Given","When","Then","And","But","def","call","eval","print","method","match","assert","url","path","request","response","status","header","headers","param","cookie","configure","karate");
boolean keywordValid = known.contains(stepText.split("\\s+", 2)[0]);

try { executor.execute(step); } catch (RuntimeException e) { if (e.getMessage().startsWith("unknown keyword: ")) { throw new IllegalStateException("fix feature line: " + e.getMessage()); } throw e; }

When it happens

Trigger: A .feature step whose first token is not a recognized Karate/Gherkin keyword and whose text does not begin with '(' — e.g. a misspelled keyword ('Def', 'whenn'), a stray word, or a step placed in a feature run through the step executor directly.

Common situations: Typos in step keywords; copying steps from another DSL; language/locale mismatches producing non-English keywords; accidentally writing plain text lines inside a Scenario; calling StepExecutor.execute programmatically with a hand-built Step.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• def requires '=' assignment
• multipart file requires '=' assignment:
• multipart field requires '=' assignment:
• input must not be null
• input string must not be empty or blank

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/StepExecutor.java:270

                    case "call" -> executeCall(step);
                    case "callonce" -> executeCallOnce(step);
                    case "eval" -> executeEval(step);
                    case "doc" -> executeDoc(step);

                    // Config
                    case "configure" -> executeConfigure(step);

                    // Browser driver
                    case "driver" -> executeDriver(step);

                    default -> {
                        // Check if text starts with ( - means keyword is a function name like myFunc('a')
                        // We only do this check here (not earlier) because valid keywords like "eval"
                        // could have text starting with ( like "eval (1 + 2)"
                        if (text != null && text.trim().startsWith("(")) {
                            runtime.eval(keyword + text, step);
                        } else {
                            throw new RuntimeException("unknown keyword: " + keyword);
                        }
                    }
                }
            }

            long elapsedNanos = System.nanoTime() - startNanos;
            StepResult result = StepResult.passed(step, startTime, elapsedNanos);
            collectLogsAndEmbeds(result);

            // Notify interceptor of successful step execution
            if (finalInterceptor != null && finalPointFactory != null) {
                Object afterPoint = finalPoint;
                if (afterPoint == null) {
                    String sourcePath = step.getFeature().getResource().getRelativePath();
                    afterPoint = finalPointFactory.create(io.karatelabs.js.DebugPointFactory.GHERKIN_STEP, step.getLine(), sourcePath, step, null);
                }
                finalInterceptor.afterExecute(afterPoint, result, null);
            }

View on GitHub (pinned to a22eb90246)