karatelabs/karate · error · RuntimeException

karate.setup() is not available in this context

Error message

karate.setup() is not available in this context

What it means

karate.setup() invokes a named setup block (executed once for e.g. one-time data seeding). It requires an active ScenarioRuntime; when called from a context without one (boot scripts, non-scenario JS, suite hooks) the library throws this availability error.

Solutions

1. Call karate.setup() from within a scenario (it is designed for scenario-scoped one-time setup)
2. Pass the optional setup block name only when using named setups: karate.setup('seed-db')
3. Move one-time data preparation to a dedicated feature executed before the suite instead of config-time JS.

Example fix

// before (karate-config.js)
karate.setup('seed-db'); // throws at boot
// after — inside a feature
Scenario: init
* karate.setup('seed-db')

// JS: invoke setup only from scenario scope
Scenario: init
* karate.setup('seed-db')

try { karate.setup('seed-db'); } catch (e) { if (String(e).indexOf('not available in this context') >= 0) karate.warn('karate.setup() requires a scenario runtime'); throw e; }

When it happens

Trigger: karate.setup('myscenario') or karate.setup() inside karate-config.js, a standalone JS eval, or any hook where getRuntime() returns null.

Common situations: Trying to run setup blocks from a suite-level or config script; calling karate.setup() in an afterScenario/afterSuite hook; embedding the Karate engine and invoking JS without a scenario in flight.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• karate.driver can only be read within a scenario
• karate.setup() requires a feature context
• karate.setupOnce() requires a feature context
• render() needs at least one argument
• render() read arg should not be null

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/core/KarateJsBase.java:362

        }
        return new KarateConfig();
    }

    JavaInvokable abort() {
        return args -> {
            ScenarioRuntime rt = getRuntime();
            if (rt != null) {
                rt.abort();
            }
            return null;
        };
    }

    JavaInvokable setup() {
        return args -> {
            ScenarioRuntime rt = getRuntime();
            if (rt == null) {
                throw new RuntimeException("karate.setup() is not available in this context");
            }
            String name = args.length > 0 && args[0] != null ? args[0].toString() : null;
            return rt.executeSetup(name);
        };
    }

    JavaInvokable setupOnce() {
        return args -> {
            ScenarioRuntime rt = getRuntime();
            if (rt == null) {
                throw new RuntimeException("karate.setupOnce() is not available in this context");
            }
            String name = args.length > 0 && args[0] != null ? args[0].toString() : null;
            return rt.executeSetupOnce(name);
        };
    }

    /**

View on GitHub (pinned to a22eb90246)