{"record":{"id":"037dedef70c8874b","repo":"karatelabs/karate","slug":"karate-setuponce-is-not-available-in-this-context","errorCode":null,"errorMessage":"karate.setupOnce() is not available in this context","messagePattern":"karate\\.setupOnce\\(\\) is not available in this context","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/KarateJsBase.java","lineNumber":373,"sourceCode":"        };\n    }\n\n    JavaInvokable setup() {\n        return args -> {\n            ScenarioRuntime rt = getRuntime();\n            if (rt == null) {\n                throw new RuntimeException(\"karate.setup() is not available in this context\");\n            }\n            String name = args.length > 0 && args[0] != null ? args[0].toString() : null;\n            return rt.executeSetup(name);\n        };\n    }\n\n    JavaInvokable setupOnce() {\n        return args -> {\n            ScenarioRuntime rt = getRuntime();\n            if (rt == null) {\n                throw new RuntimeException(\"karate.setupOnce() is not available in this context\");\n            }\n            String name = args.length > 0 && args[0] != null ? args[0].toString() : null;\n            return rt.executeSetupOnce(name);\n        };\n    }\n\n    /**\n     * karate.callonce() - Execute a feature file once per feature and cache the result.\n     */\n    JavaInvokable callonce() {\n        return args -> {\n            ScenarioRuntime rt = getRuntime();\n            if (rt == null) {\n                throw new RuntimeException(\"karate.callonce() is not available in this context\");\n            }\n            if (args.length == 0) {\n                throw new RuntimeException(\"karate.callonce() requires at least one argument (feature path)\");\n            }","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/KarateJsBase.java#L355-L391","documentation":"karate.setupOnce() registers a setup routine that runs once per feature, but it requires an active ScenarioRuntime. Karate throws this when the JS `karate` object is accessed from a context where no scenario is executing (e.g. a standalone JS engine, a background/bootstrap hook, or a non-scenario thread), because there is no runtime to attach the setup-once callback to.","triggerScenarios":"Calling `karate.setupOnce(...)` from JS evaluated outside a running scenario: before the suite starts, from a hook that lacks a ScenarioRuntime, from a custom Java embedding point, or from a JS file invoked without a scenario context (getRuntime() returns null).","commonSituations":"Moving setup code out of a scenario into an init script; wiring karate JS APIs into a custom runner or embedded JS engine; calling setupOnce from a `Background`-adjacent or parallel-thread context where the runtime has not been bound yet.","solutions":["Call karate.setupOnce() only from JS evaluated inside a running scenario/feature so getRuntime() is non-null.","If you need suite-level one-time setup outside a scenario, use the Suite/Runner level setup hooks (e.g. @BeforeSuite-style or Runner builder callbacks) instead of karate.setupOnce().","Verify the JS execution path binds a ScenarioRuntime (call within a Scenario step or configure via the runtime-bound karate instance).","Use karate.callSingle() at scenario level if the goal is once-per-suite caching rather than per-feature setup."],"exampleFix":"// before: in an init script with no scenario\nkarate.setupOnce('setupUtils');\n\n// after: called from within a scenario, or use Runner-level setup\n// Scenario: init\n// * karate.setupOnce('setupUtils')","handlingStrategy":"try-catch","validationCode":"if (karate.setupOnce && typeof scenarioBound !== 'undefined' && scenarioBound) { karate.setupOnce('setupUtils'); }","typeGuard":"function canUseScenarioApi(karateObj) { try { return karateObj != null && typeof karateObj.setupOnce === 'function' && !!getRuntime(); } catch (e) { return false; } }","tryCatchPattern":"try { karate.setupOnce('setupUtils'); } catch (e) { if (String(e.message).includes('not available in this context')) { /* fall back to Runner-level setup hook */ } else { throw e; } }","preventionTips":["Only call scenario-scoped karate APIs from inside running scenarios","Use Suite/Runner lifecycle hooks for pre-suite initialization","Bind ScenarioRuntime before evaluating karate JS in embedded engines"],"tags":["javascript","runtime-context","setup","karate"],"backgroundTag":"invalid-state-transition","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}