apache/incubator-seata · error · IllegalArgumentException

unknown session mode:{}

Error message

unknown session mode:{}

What it means

SessionMode.get(name) maps a configuration string to the SessionMode enum (file, db, redis, raft) case-insensitively; unknown values throw IllegalArgumentException 'unknown session mode:<name>'. SessionMode.contains() provides a non-throwing membership test.

Source

Thrown at common/src/main/java/org/apache/seata/common/store/SessionMode.java:49

    REDIS("redis"),
    /**
     * raft store
     */
    RAFT("raft");

    private String name;

    SessionMode(String name) {
        this.name = name;
    }

    public static SessionMode get(String name) {
        for (SessionMode mode : SessionMode.values()) {
            if (mode.getName().equalsIgnoreCase(name)) {
                return mode;
            }
        }
        throw new IllegalArgumentException("unknown session mode:" + name);
    }

    /**
     * whether contains value of store mode
     *
     * @param name the mode name
     * @return the boolean
     */
    public static boolean contains(String name) {
        try {
            return get(name) != null ? true : false;
        } catch (IllegalArgumentException e) {
            return false;
        }
    }

    public String getName() {
        return name;

View on GitHub (pinned to e01f97c6db)

Solutions

1. Use exactly file, db, redis, or raft for the session mode setting.
2. Verify the property is set and not empty at runtime before calling SessionMode.get.
3. Use SessionMode.contains(name) to pre-validate config values.

Example fix

# before
session.mode=database

# after
session.mode=db

String mode = config.get("session.mode");
if (!SessionMode.contains(mode)) {
    throw new IllegalArgumentException("session.mode must be one of file/db/redis/raft, got: " + mode);
}
SessionMode sessionMode = SessionMode.get(mode);

try {
    SessionMode mode = SessionMode.get(name);
} catch (IllegalArgumentException e) {
    // echo valid values file/db/redis/raft in the config error to speed up fixing
    throw e;
}

When it happens

Trigger: Configuring session store mode (e.g. sessionMode/seata.server.sessionMode, session.mode properties or programmatic SessionMode.get(cfg)) with a value not in {file, db, redis, raft}, including null/empty/typo values.

Common situations: Setting 'mysql' or 'database' instead of 'db'; leaving the property blank so an empty string is passed; version upgrades where a mode was renamed; copy-pasting store.mode values into session mode.

Related errors

• unknown lock mode:{}
• unknown store mode:{}
• not support config type:
• not found service provider for : {}
• "\"" + str + "\" can't parse to Duration"

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/f9d8c126170c8434. Report an issue: GitHub.