{"record":{"id":"bd18eba6fee39461","repo":"karatelabs/karate","slug":"registerglobal-name-is-null-or-empty","errorCode":null,"errorMessage":"registerGlobal: name is null or empty","messagePattern":"registerGlobal: name is null or empty","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/core/Suite.java","lineNumber":756,"sourceCode":"     * Built-in JS-scope names an ext global may not shadow. Registration of a\n     * colliding ext global fails the Suite loud at boot (see EXT.md § Ext globals).\n     */\n    // `match` is intentionally NOT reserved — core no longer ships a global `match` (assertions are the\n    // Gherkin `match` keyword + `karate.match`); a consumer may register its own `match` global.\n    private static final Set<String> RESERVED_GLOBAL_NAMES = Set.of(\"karate\", \"read\", \"driver\");\n\n    /**\n     * Register an ext global under {@code name}, seeded into every scenario's JS\n     * scope before {@code karate-config.js} evaluates. Called by an {@link Ext}\n     * from {@link Ext#onBoot(Suite)}; the instance is typically a\n     * {@link io.karatelabs.js.SimpleObject} so members cross into JS natively\n     * (no reflection). Throws — and so fails the Suite at boot — when the name is\n     * blank or collides with a built-in global ({@code karate}, {@code read},\n     * {@code match}, {@code driver}).\n     */\n    public void registerGlobal(String name, Object instance) {\n        if (name == null || name.isBlank()) {\n            throw new IllegalArgumentException(\"registerGlobal: name is null or empty\");\n        }\n        if (RESERVED_GLOBAL_NAMES.contains(name)) {\n            throw new RuntimeException(\"ext global '\" + name + \"' collides with built-in '\" + name + \"'\");\n        }\n        globals.put(name, instance);\n    }\n\n    /**\n     * Register a <em>per-scenario</em> ext global: the {@link ExtGlobalFactory} is\n     * invoked once per scenario at seed time to mint a fresh instance bound with the\n     * scenario's {@link KarateJsContext}. Prefer this over the singleton\n     * {@link #registerGlobal(String, Object)} when the global carries per-scenario\n     * mutable state or needs runtime / path access — see {@link ExtGlobalFactory}.\n     */\n    public void registerGlobal(String name, ExtGlobalFactory factory) {\n        if (name == null || name.isBlank()) {\n            throw new IllegalArgumentException(\"registerGlobal: name is null or empty\");\n        }","sourceCodeStart":738,"sourceCodeEnd":774,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/core/Suite.java#L738-L774","documentation":"Suite.registerGlobal(String, Object) validates the global name before storing it. Karate throws this IllegalArgumentException at Suite boot when the name argument is null or a blank string, because a global binding without a name can never be referenced from scripts. Throwing loud at boot prevents silently registering an unusable global.","triggerScenarios":"Calling suite.registerGlobal(null, myInstance) or suite.registerGlobal(\"\", myInstance) (or a whitespace-only name like \"   \") before running the suite.","commonSituations":"The name is computed dynamically (e.g. from a config value, environment variable, or a constants class where the constant itself is null); refactoring renamed the constant away leaving null; the caller passes a variable initialized later.","solutions":["Check the value passed as the name argument and ensure it is a non-null, non-blank String literal or constant","If the name comes from config/env, add a null/blank check with a clear failure message before calling registerGlobal","If overloading confusion is possible, verify you are calling the (String, Object) overload with arguments in the right order"],"exampleFix":"// before\nsuite.registerGlobal(System.getProperty(\"ext.global.name\"), new MyHelper());\n// after\nString name = System.getProperty(\"ext.global.name\");\nif (name == null || name.isBlank()) throw new IllegalArgumentException(\"ext.global.name must be set\");\nsuite.registerGlobal(name, new MyHelper());","handlingStrategy":"validation","validationCode":"if (name == null || name.isBlank()) throw new IllegalArgumentException(\"global name required\");\nsuite.registerGlobal(name, instance);","typeGuard":"boolean usableName(String n) { return n != null && !n.isBlank(); }","tryCatchPattern":null,"preventionTips":["Use a compile-time constant for global names","Validate names sourced from config/env before registration","Register globals in one reviewed init method"],"tags":["java","configuration","argument-validation"],"backgroundTag":"null-argument","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}