We put a 100,002-user Keycloak database (224 MB) on a small filesystem and upgraded 26.0.0 → 26.7.1 with the free space set to an exact figure each time. With 8 MB free it completed in 17 seconds and consumed 1.58 MB. With 4 MB it died:
ERROR: could not write to file "base/pgsql_tmp/...": No space left on device
[Failed SQL: (0) CREATE INDEX IDX_USER_CREATED_TIMESTAMP ON public.USER_ENTITY(REALM_ID, CREATED_TIMESTAMP)]
base/pgsql_tmp is the giveaway. The space that ran out is not the space the index occupies. It is the temporary sort file Postgres needs to build it, which is larger than the result. Free space equal to your index size is not enough.
The failure is real, and it is kind. It left a half-applied schema: 187 of 211 changesets committed, migration_model still on the old version. Freeing space and restarting completed it in 17 seconds: changelog 211, model 26.7.1, index built, all 100,002 users present, admin login returning 200. If you find a Keycloak stopped partway through a migration, the first thing to try is starting it again, after you have fixed whatever stopped it.
The counter-intuitive part, and its correction
Our first conclusion was that the bigger realm is the safer one. That index is the one Keycloak refuses to build on tables over 300,000 rows, so a 2-million-user realm never runs the sort and never hits this. The vulnerable realms are the small ones.
That sentence needs its condition attached. The skip reads pg_class.reltuples, and a stale estimate makes Keycloak build anyway, at any true size. We forced the build at 2,000,003 users, and the floor moved from (4 MB, 8 MB] to (125 MB, 150 MB] - roughly 20× the 100k figure.
The transient is the reason, and the finished index is not. That index is 14 MB; the net disk consumed by the build is 14 MB; the free space actually required is over 125 MB. Sizing headroom from the finished index - the obvious thing to do - is wrong by an order of magnitude, and wrong in the direction that fails. The sort spills to disk beyond maintenance_work_mem (64 MB stock), in parallel (two maintenance workers by default).
Scaling up does not remove the failure mode. It removes the trigger, and multiplies the damage if anything pulls it - a stale statistic, or a customer who manually created the skipped indexes, re-arms this at any size.
What to check
- Size the disk check from row count, not database size. Budget roughly
~10× the expected index size, or ~70 bytes per row for a two-column index on
USER_ENTITY. At 2M that is ~150 MB; at 10M, expect ~700 MB. could not write to file "base/pgsql_tmp/..."means temp space, not table space. Freeing space anywhere on that filesystem is enough.- Recovery is a restart once space exists. Fix the cause, start Keycloak,
verify
migration_model.
What we did not test: the floor with maintenance_work_mem raised, with parallel maintenance workers disabled, a full (0-byte) disk, and any point between 100k and 2M.
Keycloak Advisory Watch - one email per advisory batch, within 72 hours of publication, listing the patched versions per maintained minor line. Double opt-in, no tracking pixels, no click tracking, public archive. Subscribe.
Self-hosted Keycloak is one of the things we keep patched, upgraded and owned for teams that run it but have nobody to run it. Talk to us about your project.
Sources: 2026-08-25-s14-disk-exhaustion, 2026-08-26-s14-revisited-disk-floor-at-2m.