karatelabs/karate · error · RuntimeException

switch() requires a template argument

Error message

switch() requires a template argument

What it means

The server context's switch() method switches server-side processing to another template and requires one template-name argument. Calling switch() with no arguments throws this RuntimeException before any template lookup happens.

Solutions

1. Pass the template name explicitly: context.switch('other-template').
2. Guard the template-name variable and fall back to a default template when missing.
3. Verify the expression computing the template name (e.g. request params) isn't yielding undefined.
4. If conditional rendering is the goal, use an if in markup instead of switch().

Example fix

// before
context.switch(nextPage); // undefined
// after
context.switch(nextPage || 'default-template');

// JS in markup
if (typeof tpl !== 'string' || !tpl) tpl = 'default-template';

When it happens

Trigger: Calling context.switch() without arguments in server markup JavaScript — usually a template name variable that is undefined/empty at call time, or calling switch() for its side effects expecting it to be a no-op.

Common situations: Multi-template server flows (e.g. switching between login and error pages) where the next-template name is derived from request data; typos between switch() and switchTemplate; dynamic routing handlers in Karate mock servers.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• doc() requires 'read' key with template path
• redirect() requires a URL argument
• context.setGlobal() requires a name argument
• context.getGlobal() requires a name argument
• doc() needs at least one argument

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

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/ServerMarkupContext.java:367

                if (args.length == 0) throw new RuntimeException("redirect() requires a URL argument");
                redirect(args[0].toString());
                return null;
            };
            case "log" -> (JavaInvokable) args -> {
                log(args);
                return null;
            };
            case "uuid" -> (JavaInvokable) args -> uuid();
            case "init" -> (JavaInvokable) args -> {
                init();
                return session;  // Return session so scripts can do: session = context.init()
            };
            case "close" -> (JavaInvokable) args -> {
                close();
                return null;
            };
            case "switch" -> (JavaInvokable) args -> {
                if (args.length == 0) throw new RuntimeException("switch() requires a template argument");
                switchTemplate(args[0].toString());
                return null;
            };
            case "setGlobal" -> (JavaInvokable) args -> {
                if (args.length == 0 || args[0] == null) {
                    throw new RuntimeException("context.setGlobal() requires a name argument");
                }
                String name = args[0].toString();
                Object value = args.length > 1 ? args[1] : null;
                setGlobal(name, value);
                return null;
            };
            case "getGlobal" -> (JavaInvokable) args -> {
                if (args.length == 0 || args[0] == null) {
                    throw new RuntimeException("context.getGlobal() requires a name argument");
                }
                String name = args[0].toString();
                Object defaultValue = args.length > 1 ? args[1] : null;

View on GitHub (pinned to a22eb90246)