karatelabs/karate · error · RuntimeException

no scenario found with @setup tag

Error message

no scenario found with @setup tag[ and name '<name>']

What it means

executeSetup looks up the @setup scenario via feature.getSetup(name). If the feature contains no @setup-tagged scenario matching the optional name argument, a RuntimeException with this message is thrown, naming the requested setup when one was supplied. It is a feature-authoring error, not a runtime failure.

Solutions

  1. Add a scenario tagged @setup to the current feature (with the matching name if karate.setup('name') is used).
  2. Verify exact spelling of the name passed to karate.setup('name') against the setup scenario's name.
  3. Remember the @setup scenario must be in the same feature — call the other feature with karate.call() instead if setup lives elsewhere.
  4. Call karate.setup() with no argument only when the feature has exactly one default @setup scenario.

Example fix

// before
# feature has no setup, but JS does:
* def data = karate.setup()

// after
@setup
Scenario:
  * def data = { userId: 1 }

# then
* def data = karate.setup()
Defensive patterns

Strategy: validation

Validate before calling

// before karate.setup('name'), confirm the setup exists in THIS feature:
// @setup
// Scenario: makeData  <-- name must match exactly

Try / catch

try {
    var data = karate.setup('makeData');
} catch (e) {
    if (String(e).indexOf('no scenario found with @setup tag') >= 0) {
        karate.log('setup missing; falling back to inline data');
        data = { userId: 1 };
    } else { throw e; }
}

Prevention

When it happens

Trigger: karate.setup() with no argument when the feature has no @setup scenario at all; karate.setup('name') when no @setup scenario carries that exact name/tag combination; a typo in the setup name; the @setup tag missing from the intended scenario.

Common situations: Copying scenarios between features without copying the @setup block; renaming a setup scenario but not all karate.setup('name') call sites; assuming setup is inherited from a called feature (it is not — setup is per-feature).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

            logger.warn("Failed to evaluate {}: {}", displayName, e.getMessage());
            throw new RuntimeException("Config evaluation failed: " + displayName + " - " + e.getMessage(), e);
        }
    }

    /**
     * Execute the @setup scenario and return all its variables.
     */
    public Map<String, Object> executeSetup(String name) {
        if (featureRuntime == null) {
            throw new RuntimeException("karate.setup() requires a feature context");
        }
        Scenario setupScenario = scenario.getFeature().getSetup(name);
        if (setupScenario == null) {
            String message = "no scenario found with @setup tag";
            if (name != null) {
                message = message + " and name '" + name + "'";
            }
            throw new RuntimeException(message);
        }
        // Run the setup scenario without background
        ScenarioRuntime sr = new ScenarioRuntime(featureRuntime, setupScenario);
        sr.setSkipBackground(true);
        sr.call();
        // The setup runtime re-evaluates config, and a failure there is now captured rather than
        // thrown from the constructor. call()'s failed result is discarded here, so without this the
        // caller gets an empty variable map and the config error resurfaces as a baffling
        // "x is not defined" wherever a setup variable was expected. Fail where the cause is.
        Throwable setupConfigError = sr.getConfigError();
        if (setupConfigError != null) {
            throw setupConfigError instanceof RuntimeException re ? re : new RuntimeException(setupConfigError);
        }
        return sr.getAllVariables();
    }

    /**
     * Execute the @setup scenario with caching (only runs once per feature).

View on GitHub (pinned to a22eb90246)