keystone

Breaking changes

What to check before upgrading, taken from the notes of the last 30 releases.

• 2026-07-28Jul 28, 2026

  Breaking Changes

  • [core] Upgrades Prisma major version to 7. prisma and @prisma/client are now peer dependencies of @keystone-6/core. You will need to install them in your project along with the relevant adapter for your database (e.g. @prisma/adapter-pg). The db.url, db.shadowDatabaseUrl, and db.enableLogging config options have been replaced with a prismaClientOptions option, this is a function which should return the configuring Prisma adapter and any other options you want to pass to the Prisma client. The Prisma Client is now generated into generated/prisma by default now (#9872) @emmatown
  • [core] Removes the keystone prisma command, you should use prisma directly. (#9872) @emmatown
  • [core] Removes the keystone migrate commands and the --with-migrations option, you should use prisma directly. (#9872) @emmatown
  • [core] Replaces @keystone-6/core/testing's resetDatabase function with new implementations in @keystone-6/core/testing/postgresql, @keystone-6/core/testing/sqlite and @keystone-6/core/testing/mysql (#9872) @emmatown
  • [auth, cloudinary, core, create-keystone-app, document-renderer, fields-document] Changes package to exclusively Node ESM. This is intended to be used by require(esm) and should not affect consumers beyond requiring a modern Node version. keystone build outputs are still CommonJS. (#9929) @emmatown
  • [core] Moves the default field mode configuration from ui.*.defaultFieldMode to fieldDefaults.ui.*.fieldMode on lists and field groups. (#9882) @emmatown
  • [core] Fixes the password field to throw an error for inputs longer than 72 bytes when using the default bcrypt key derivation function (KDF) (#9486) @emmatown
  • [core] Changes the sudo boolean on GraphQL schema extensions to scope, which is either 'public' or 'internal'. Code that previously checked schema.extensions.sudo should now check schema.extensions.scope === 'internal'. (#9914) @emmatown
  • [core] Changes displayMode: 'count' on relationship fields to require itemView.fieldMode: 'read' or a dynamic fieldMode that only resolves to 'read' or 'hidden'. (#9528) @emmatown
  • [auth] Removes magicAuthLink and passwordResetLink functionality from @keystone-6/auth (#9245) @dcousens
  • [core] Removes {list}.description and {list}.ui.description, retains {list}.graphql.description functionality (#9672) @dcousens
  • [core] Removes null value from {field}.ui.description, replace with empty string or omit the key (#9672) @dcousens
  • [core] Changes field meta from {field}.path to {field}.key, as used by field views (#9671) @dcousens
  • [core] Moves storage configuration to image and file fields, with a new StorageStrategy interface that directly defines how put, delete and url functions (#9529) @emmatown
  • [auth, core, fields-document] Updates to graphql@^16.14.2, graphql is now also a peer dependency in addition to a normal dependency so if you have a dependency on graphql yourself, you must have a compatible version installed (#9956) @emmatown
  • [core] Moves {field}.label to {field}.ui.label (#9631) @dcousens
  • [core] Changes the type for ui.getAdditionalFiles to be flattened, prefer function composition when wrapping (#9681) @dcousens
  • [core] Removes the deprecated --fix flag from keystone postinstall (#9190) @gautamsi
  • [core] Updates @apollo/server to v5 (#9880) @trickreich
  • [core] Adds itemField, originalItemField, inputFieldData and resolvedFieldData parameters to field hooks (#9600) @dcousens
  • [core] Removes the isFilterable, isOrderable, defaultIsFilterable, and defaultIsOrderable configuration options. Field read access can now distinguish between reading an item, filtering, and ordering through access.read.item, access.read.filter, and access.read.order. The corresponding GraphQL schema fields can be omitted through graphql.omit.read, with list-wide defaults configured through fieldDefaults.access and fieldDefaults.graphql.omit. (#9883) @emmatown
  • [create-keystone-app] Removes auto-install, use your preferred package manager to install dependencies instead (#9942) @emmatown
  • [core] Changes the method by which .sudo() bypasses access control, with context.sudo().graphql.schema now retaining access control as part of the GraphQL schema (#9731) @dcousens
• 2026-07-21Jul 21, 2026

  Breaking Changes

  • [core] Upgrades Next major version to 15 (#9809) @AlanBreck @MauriceArikoglu
  • [auth, cloudinary, core, fields-document] Upgrades React major version to 19 (#9809) @AlanBreck @MauriceArikoglu
• 2024-04-16Apr 16, 2024

  Breaking Changes

  • [core] Changes file and image to use random 128-bit base64url identifiers by default, not uuid (#9079) @dcousens
  • [core] Removes AdminUIConfig, DatabaseConfig, GraphQLConfig and ServerConfig from @keystone-6/core/types, and some unused types - instead use KeystoneConfig['ui'], KeystoneConfig['db'] and so on (#9085) @dcousens
  • [core] Removes @keystone-6/core/system from exports (#9085) @dcousens
  • [core] Upgrade @prisma/* packages to 5.12.1 (#9088) @dcousens, @borisno2
  • [core] Removes unused type parameters from types ListConfig and ListAdminUIConfig (#9083) @dcousens
  • [core] Remove the deprecated type parameters from the list and group functions (#9083) @dcousens
  • [core] Removes graphqlSchema parameter from extendHttpServer, use context.graphql.schema instead (#9083) @dcousens
  • [core] Moves config.extendGraphqlSchema to config.graphql.extendGraphqlSchema, similar to db.extendPrismaSchema (#9083) @dcousens
  • [core] Remove KeystoneConfig parameter from getAdditionalFiles function type (#9083) @dcousens
  • [core] Remove the deprecated context.exitSudo from KeystoneContext (#9083) @dcousens
  • [core] Remove context.experimental.initialisedLists, use context.__internal.lists (may break in patch) (#9083) @dcousens
  • [core] Remove ExtendGraphqlSchema type alias, use (schema: GraphQLSchema) => GraphQLSchema instead (with import type { GraphQLSchema } from 'graphql'). (#9083) @dcousens, @emmatown
  • [core] Remove the deprecated (#8721) config.server.healthCheck, use extendExpressApp instead (#9083) @dcousens
  • [core] Removes ListSchemaConfig type, use KeystoneConfig['lists'] instead (#9083) @dcousens
  • [core] Remove db.additionalPrismaDatasourceProperties, use extendPrismaSchema if needed (#9083) @dcousens
  • [core] Remove db.prismaPreviewFeatures, use extendPrismaSchema if needed (#9083) @dcousens
  • [core] Remove any type parameter from SessionStore/SessionStoreFunction types (#9083) @dcousens
  • [core] Remove deprecated config.db.useMigrations, use --with-migrations process argument or keystone prisma migrate [dev|deploy] instead (#9090) @dcousens
  • [core] Change keystone prisma behaviour to first require keystone build (or keystone dev) (#8776) @dcousens, @borisno2