Should I upgrade to Keycloak 26 Persistent User Sessions Upgrade and Cache Sizing Decision now?
Teams upgrading self-hosted Keycloak need to know how the Keycloak 26 persistent-user-session defaults change memory, database load, and cluster sizing before they roll forward.
Blockers
- Keycloak 26 enables persistent-user-sessions by default and changes remote-store behavior for user-session caches.
- Migration of existing online sessions from Keycloak 24 or earlier only worked when persistent-user-sessions was enabled on the first start of Keycloak 25.
- Keycloak 26 still allows volatile user sessions, but unsupported custom owner and cache-size settings are ignored in favor of safe defaults.
- Lock-in via capability/multi-site
Who this is for
- enterprise
- high-scale
- cost-sensitive
- compliance
Candidates
Adopt Keycloak 26 default persistent user sessions and resize around the database
As of 2026-03-27, Keycloak 26 enables `persistent-user-sessions` by default, so regular user and client sessions are stored in the database and loaded on demand into the `sessions` and `clientSessions` caches. The default in-memory caches for user, client, offline user, and offline client sessions are limited to 10000 entries per node, and the internal caches run with only a single owner for each cache entry. Keycloak documents that if concurrent sessions exceed the cache maximum, database activity and request latency increase because session data must be reloaded during operations such as token refresh or user-info calls. This path reduces Keycloak memory footprint versus the older all-in-memory model, but it shifts more steady-state load and sizing risk to the database.
When to choose
Use this for the normal Keycloak 26 single-site upgrade path when you want sessions to survive restarts and upgrades. It is the decisive choice when restart resilience matters more than minimizing database reads, and when you can provision and observe the database as the new source of truth for online sessions.
Tradeoffs
Lower Keycloak memory use and no need for single-site external Infinispan to preserve sessions, but more read/write pressure moves to the database and cache miss latency becomes user-visible if cache sizing is too small.
Cautions
If you upgraded from Keycloak 24 or earlier, migration of existing online sessions only worked when `persistent-user-sessions` was enabled on the first start of Keycloak 25. If you moved to Keycloak 25 without enabling it, Keycloak documents there is no later migration path; you must clear existing online sessions before first starting nodes with the feature enabled. Keycloak 26 also restricts embedded remote-store usage: if `persistent-user-sessions` is disabled and remote store is configured for user-session caches, startup is refused, and if the feature is enabled the remote-store configuration is ignored with a warning.
Disable persistent user sessions and keep volatile in-memory sessions
As of 2026-03-27, Keycloak 26 still allows volatile user sessions by starting with `--features-disabled=persistent-user-sessions`. In this mode, the cache becomes the source of truth for regular user and client sessions, which minimizes database calls for active sessions but brings back the older failure mode where all sessions are lost if all Keycloak nodes restart. Keycloak explicitly calls out increased memory consumption for this setup. Current Keycloak 26 releases also state that problematic custom owner and cache-size settings for volatile session caches are ignored in favor of safe defaults, and teams should revert to the standard cache configuration file rather than carry old `cache-ispn.xml` tweaks forward.
When to choose
Use this only when database pressure is the immediate bottleneck and you can accept restart-driven logout events. It is the decisive option for single-site deployments that value lower database activity over session durability across maintenance windows.
Tradeoffs
Lower database usage for active sessions, but higher Keycloak memory consumption and guaranteed loss of online sessions on full-cluster restarts. It also removes the main operational benefit of the Keycloak 26 default.
Cautions
Keycloak says setting maximum cache size for `sessions` and `clientSessions` is not supported when volatile sessions are enabled. Disabling `persistent-user-sessions` is also not possible when the `multi-site` feature is enabled.
Evaluate experimental external Infinispan session storage only if database load is unacceptable
As of 2026-03-27, Keycloak 26 documents an experimental `clusterless` path where sessions are stored in external Infinispan instead of the database, with `persistent-user-sessions` disabled. Keycloak says this reduces database usage, but it also labels the feature experimental and not yet fully finished or performance-optimized. For older single-site patterns that used embedded remote stores to survive restarts, Keycloak 26 treats that approach as obsolete, deprecated, and scheduled for removal in the next major release. This makes pure external Infinispan an evaluation path, not the standard production upgrade target.
When to choose
Use this only for controlled testing when persistent sessions put unacceptable pressure on the database and your team can tolerate experimental behavior. The decisive factor is a proven database bottleneck combined with willingness to own extra complexity and feature risk.
Tradeoffs
Potentially reduced database load, but higher architecture complexity and weaker support posture. It also keeps you closer to features Keycloak is actively warning about or deprecating.
Cautions
Keycloak states the single-site memory-plus-external-Infinispan pattern is deprecated and will be removed in the next major release. For multi-site, Keycloak forces persistent user sessions unless you intentionally evaluate the experimental `multi-site,clusterless` combination.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to Keycloak 26 Persistent User Sessions Upgrade and Cache Sizing Decision now?"