karatelabs/karate · error · RuntimeException

session is unavailable: no sessionStore is configured. Call…

Error message

session is unavailable: no sessionStore is configured. Call ServerConfig.sessionStore(...) at app startup to enable sessions. Attempted to read session.{name}

What it means

ServerMarkupContext exposes a SessionUnavailableProxy for the 'session' object when no session store is configured on the HTTP server. Any property read or write on that proxy throws this exception explaining that ServerConfig.sessionStore(...) must be called at startup. It converts a would-be null session into a clear, actionable failure inside template/JS evaluation.

Solutions

  1. Call ServerConfig.sessionStore(...) at app startup to enable sessions before serving pages that use session
  2. Remove or guard session usage in templates when sessions aren't needed (e.g. conditionally render)
  3. If sessions should exist, verify the ServerConfig used to build the server is the intended one

Example fix

// before
ServerConfig config = new ServerConfig().staticFeatures(true);
// after
ServerConfig config = new ServerConfig()
    .sessionStore(new InMemorySessionStore())
    .staticFeatures(true);
Defensive patterns

Strategy: validation

Validate before calling

// at server startup, verify sessions are configured before serving templates that use session
if (serverConfig.getSessionStore() == null) throw new IllegalStateException('session usage requires ServerConfig.sessionStore(...)');

Try / catch

try { var user = session.user; } catch (e) { karate.warn('session unavailable: ' + e); var user = null; }

Prevention

When it happens

Trigger: Server-side template or JS (e.g. in a Karate mock/HTML page served by the dev server) references session.<name> while the server was built without a sessionStore in ServerConfig.

Common situations: Templates using session variables on a server started without session configuration; forgetting sessionStore() when enabling auth/session features; local mock servers that never had sessions set up.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

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

            // `if (session) { session.foo }` pattern that would silently skip
            // the branch when session is null now enters and fails noisily,
            // pointing the developer at ServerConfig.sessionStore(...).
            vars.put("session", SessionUnavailableProxy.INSTANCE);
        }
        return vars;
    }

    /**
     * Placeholder for the {@code session} binding when no sessionStore
     * is configured. Throws a clear, actionable error on any access.
     */
    private static final class SessionUnavailableProxy implements io.karatelabs.js.ObjectLike {

        static final SessionUnavailableProxy INSTANCE = new SessionUnavailableProxy();

        @Override
        public Object getMember(String name) {
            throw sessionUnavailable(name, false);
        }

        @Override
        public void putMember(String name, Object value) {
            throw sessionUnavailable(name, true);
        }

        @Override
        public void removeMember(String name) {
            throw sessionUnavailable(name, true);
        }

        @Override
        public Map<String, Object> toMap() {
            throw sessionUnavailable("(toMap)", false);
        }

        private static RuntimeException sessionUnavailable(String name, boolean write) {

View on GitHub (pinned to a22eb90246)