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 write session.{name}

What it means

Karaté throws this when a template or script accesses `session.<name>` in server-side markup, but no session store was configured on the server. Sessions are opt-in: without a SessionStore there is no backing storage for session variables, so any read or write fails fast with an actionable message. The `write` variant (putMember) is triggered when assigning to a session key.

Solutions

Call `ServerConfig.sessionStore(...)` (e.g. with an in-memory or custom SessionStore implementation) at app startup before starting the server.
Remove or guard the `session.<name>` write in the markup if session state is not actually needed.
Use request-scoped or template-local variables instead of the session for state that does not need to persist across requests.

Example fix

// before
new HttpServer(config -> config.requestHandler(...)); // no sessionStore

// after
new HttpServer(config -> config
    .sessionStore(new InMemorySessionStore())
    .requestHandler(...));

Defensive patterns

Strategy: validation

Validate before calling

// at startup, fail fast if sessions are used but not configured
if (usesSessions && serverConfig.getSessionStore() == null) {
    throw new IllegalStateException("sessionStore must be configured for session-based markup");
}

Prevention

Always call ServerConfig.sessionStore(...) in the shared server bootstrap used by all apps.
Add a startup smoke test that renders one session-using template.
Keep session usage centralized so configuration and usage cannot drift apart.

When it happens

Trigger: Evaluating server-side markup that executes `session.myVar = value` (putMember on the SessionBinding) when the HTTP server was built without `ServerConfig.sessionStore(...)`.

Common situations: Developers adding session-based state to templates after the server was already configured; copying markup from a project that uses sessions into a new app that never enabled the session store; assuming sessions work by default.

Related errors

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

Appendix: source

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

        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) {
            return new RuntimeException(
                    "session is unavailable: no sessionStore is configured. "
                            + "Call ServerConfig.sessionStore(...) at app startup to enable sessions. "
                            + "Attempted to " + (write ? "write" : "read") + " session." + name);
        }

View on GitHub (pinned to a22eb90246)