karatelabs/karate · warning

failed to hot reload step

Error message

failed to hot reload step: {}

What it means

During dev-mode hot reload, Karate detects that an edited step's text changed and tries to re-parse the step in place. If `parseAndUpdateFrom` throws (invalid step syntax after the edit), this warning is logged and the reload for that step is skipped; the run continues with the old step.

Solutions

1. Fix the syntax of the edited step line and save again to trigger a fresh hot reload
2. Restart the debug session if the step remains stale
3. Validate the step text standalone (paste into a clean feature and run once)

Example fix

// before (broken step text saved during debug)
And match response.foo == 
// after
And match response.foo == '#string'

// Mentally lint the edited line before saving during a debug session:
// every match/eval expression must be complete and quoted

When it happens

Trigger: Editing a .feature file while a debug session is running and saving a step with broken Gherkin/step syntax so `Step.parseAndUpdateFrom(newText)` throws.

Common situations: Half-finished edits saved by autosave; malformed match expressions or JS in the edited line; mismatched triple-quotes or table rows.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• pretty() needs one argument
• input must not be null
• input string must not be empty or blank
• invalid json: input is null or blank
• invalid json: not a JSON object or array

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/ScenarioRuntime.java:1862

        Resource resource = feature.getResource();
        if (resource.getPath() == null) {
            return false; // in-memory resource: nothing to reload from disk
        }
        Feature reloaded = Feature.read(Resource.from(resource.getPath()));
        for (Step oldStep : steps) {
            Step newStep = reloaded.findStepByLine(oldStep.getLine());
            if (newStep == null) {
                continue;
            }
            String oldText = canonicalStepText(oldStep);
            String newText = canonicalStepText(newStep);
            if (!oldText.equals(newText)) {
                try {
                    oldStep.parseAndUpdateFrom(newText);
                    logger.info("hot reloaded line: {} - {}", newStep.getLine(), newText);
                    success = true;
                } catch (Exception e) {
                    logger.warn("failed to hot reload step: {}", e.getMessage());
                }
            }
        }
        return success;
    }

    private static String canonicalStepText(Step step) {
        String keyword = step.getKeyword();
        String text = step.getText() == null ? "" : step.getText();
        return keyword == null ? text : keyword + " " + text;
    }

    // ========== Debug Step Navigation ==========

    /**
     * Move execution back one step (for debugging).
     * After calling this, the previous step will be re-executed.
     */

View on GitHub (pinned to a22eb90246)