Breaking changes46(No downgrade1)
Experimental DCR removed from the auth backend
No downgradeAffectsauth backend setups using experimental DCR, including those with auth.experimentalDynamicClientRegistration configured or DCR clients and sessions in the database
Action requiredCIMD or clients pre-registered through auth.staticClients, with auth.experimentalDynamicClientRegistration removed
No downgrade(Inferred: The migration deletes DCR clients and sessions, and restoring them would require recovering that deleted state.)
The migration deletes DCR clients and their authorization and offline sessions, invalidating their authorization codes and refresh tokens. Users must sign in again, though already-issued user tokens remain valid until they expire.
Show release-note lines
The deprecated experimental Dynamic Client Registration (DCR) support has been removed from the auth backend. Use Client ID Metadata Documents (CIMD), or pre-register clients through `auth.staticClients`, and remove `auth.experimentalDynamicClientRegistration` from your configuration. The database migration deletes DCR clients and their authorization and offline sessions, invalidating their authorization codes and refresh tokens. Users must sign in again through a CIMD or pre-registered client; already-issued user tokens remain valid until they expire. See the [DCR migration guide](../ai/mcp-actions.md#migrating-from-dynamic-client-registration).
github.com/backstage/backstage/releases/tag/v1.57.0useRouteRefParams returns only declared route parameters
Affectscode using useRouteRefParams
Previously, the hook could return an undeclared splat parameter. Code that relied on it now receives only parameters declared by the route ref.
Show release-note lines
`RouterBlueprint`, the `app/root` router input, and `convertLegacyAppOptions({ components: { Router } })` are no longer supported. Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components. Framework navigation destinations must start with `/` and exclude the deployment basename; use a page adapter for path-relative navigation. `useRouteRefParams` now returns only the parameters declared by its route ref, without an undeclared splat parameter. Apps using the old front-end system keep their existing routing setup.github.com/backstage/backstage/releases/tag/v1.57.0Extension attachment type replacement
Affectscode using ExtensionAttachTo(Inferred)
Consumers now use Extension<unknown>['attachTo'].
Show release-note lines
- Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.github.com/backstage/backstage/releases/tag/v1.57.0Frontend useApi now unwraps promise-valued Utility API refs
Affectspromise-valued Utility API refs used with useApi from @backstage/frontend-plugin-api
Action requiredWhen changing an existing API ref to a promise, update its consumers and custom factories together.
Previously, this hook returned the promise directly; it now unwraps the API, suspending while it loads and sending rejection reasons to an error boundary. Consumers that need the promise must use useApiHolder().get(ref).
Show release-note lines
### **BREAKING**: Lazy Utility API implementations
Utility API factories can now load implementations on demand through dynamic imports. Declare the API value as a promise, for example `ApiRef<Promise<WorkApi>>`. The `useApi` hook from `@backstage/frontend-plugin-api` unwraps the promise, suspends while it is pending, and throws rejection reasons to an error boundary:
```ts
const workApiRef = createApiRef<Promise<WorkApi>>().with({
id: 'plugin.example.work',
});
const workApi = useApi(workApiRef); // WorkApi
```
The hook's return type is now `Awaited<T>`. Consumers that intentionally used a promise returned by `useApi` must switch to `useApiHolder().get(ref)`. Changing an existing API ref to a promise changes its public contract, so update its consumers and custom factories together. Holders and factory dependencies continue to receive the declared API value unchanged. The legacy `useApi` hook from `@backstage/core-plugin-api` continues returning promises directly.github.com/backstage/backstage/releases/tag/v1.57.0Synchronous mocks for promise-valued APIs accepted
Affectstests using TestApiProvider, other mock API overrides, or renderInTestApp with promise-valued APIs or mocks
Previously, synchronous mocks for promise-valued APIs were not accepted; tests can now keep synchronous assertions when rendering is otherwise synchronous. While promise-valued mocks resolve, renderInTestApp supplies an empty Suspense fallback, so tests that relied on an ancestor boundary's loading UI may need updated assertions.
Show release-note lines
Page extension boundaries provide Suspense and error handling; consumers outside those boundaries must provide their own. `TestApiProvider` and other mock API overrides accept synchronous mocks even for promise-valued APIs, so tests can keep synchronous assertions when rendering is otherwise synchronous. Promise-valued mocks are also supported, with `renderInTestApp` supplying an empty Suspense fallback while they resolve. Tests that relied on an ancestor boundary's loading UI may need updated assertions. See the [Utility API documentation](../frontend-system/utility-apis/02-creating.md) for lazy factories and migration guidance.
github.com/backstage/backstage/releases/tag/v1.57.0Test app helpers now throw on reported creation errors
AffectsTests using renderInTestApp, renderTestApp, or createExtensionTester
Action requiredInvalid test setups need to be fixed, or intentional errors allowed through isExpectedError; API overrides need to use the test app's apis option rather than a conflicting factory in extensions.
renderInTestApp and renderTestApp could previously let a test pass for a broken app. Now errors reported during app or extension-tree creation fail the test, including errors a real app only logs as warnings, unless isExpectedError accepts them.
Show release-note lines
`renderInTestApp`, `renderTestApp`, and `createExtensionTester` now throw for all errors reported while creating the test app or extension tree, including errors that a real app only logs as warnings. Fix invalid test setups, or allow an intentional error through the `isExpectedError` option. API overrides belong in the test app's `apis` option; a conflicting factory supplied through `extensions` is rejected. Contributed by [@dyatko](https://github.com/dyatko) in [#36333](https://github.com/backstage/backstage/pull/36333).
github.com/backstage/backstage/releases/tag/v1.57.0Test apps now use per-app in-memory storage
Affectstest apps that depend on browser storage, visible notifications, global error handling, or alert replay for late subscribers
Action requiredAn explicit API implementation for tests that depend on browser storage, visible notifications, or global error handling
Toasts and errors are collected without display, and alerts are no longer replayed to late subscribers; previously, late subscribers received replayed alerts.
Show release-note lines
Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
github.com/backstage/backstage/releases/tag/v1.57.0Production JSON logs gain per-line timestamps
Affectssetups using production JSON logs
Action requiredLog pipelines and dashboards that consume the request-log date field or date prefix need to use timestamp; custom JSON logger formats need format.combine(format.timestamp(), format.json()) to preserve it.
Previously, only root HTTP router request logs had a date field, repeated at the start of message; other production JSON log lines had no timestamp. Standard logs now omit those request-log values, while custom logger formats do not retain the timestamp unless they include the required format combination.
Show release-note lines
Production JSON logs now include a `timestamp` field on every line. Root HTTP router request logs no longer include a `date` field or repeat the date at the start of the message. Update log pipelines and dashboards that read either of those values to use `timestamp`. Custom JSON logger formats should combine `format.timestamp()` with `format.json()` to preserve the field.
github.com/backstage/backstage/releases/tag/v1.57.0LDAP organization ingestion now requests mapped attributes by default
AffectsLDAP organization entity provider and LdapOrgReaderProcessor configurations
Action requiredCustom transformers needing attributes beyond the mappings must have them listed in users.options.attributes or groups.options.attributes, or request all attributes with ['*', '+']. Explicitly configured lists must include every attribute needed by mappings, vendor configuration, and transformers.
Previously, searches included all LDAP attributes, so custom transformers could read attributes beyond the mappings. After upgrading, those additional attributes may be missing from LDAP entries.
Evidence“**BREAKING**: Searches no longer request `['*', '+']` by default. This applies to both the org entity provider and `LdapOrgReaderProcessor`. When options.attributes is not explicitly configured, attributes required by map (including custom map.\* overrides and membership mappings) are requested automatically. When options.attributes is explicitly configured, the provided list is used as-is and must include all attributes required by mappings, vendor configuration, and custom transformers. Custom transformers that access other attributes from LDAP entries may now find those attributes missing.” backstage/backstage/pull/35319 ↗ Show release-note lines
LDAP organization ingestion now requests only the attributes used by configured mappings, instead of `['*', '+']`. This affects both the entity provider and `LdapOrgReaderProcessor`. Custom transformers that read additional attributes must list them in `users.options.attributes` or `groups.options.attributes`, or explicitly use `['*', '+']` to request all attributes. An explicitly configured list is used as-is and must include every attribute needed by mappings, vendor configuration, and transformers.
github.com/backstage/backstage/releases/tag/v1.57.0LDAP entity provider defaults to parallel reads
AffectsLDAP entity providers connected to directories with connection limits that require sequential reads
Action requiredSet disableParallelReads: true on the provider for directories whose connection limits require sequential reads.
Previously, each refresh read users and groups sequentially over one LDAP connection. Now it opens two connections and binds per refresh unless disableParallelReads: true is set.
Evidence“The LDAP org entity provider now reads users and groups in parallel by default. Set `disableParallelReads: true` to use one connection and read sequentially. Parallel reads open two binds and two connections per refresh. Directories with per-client connection limits may notice the extra load after upgrading.” backstage/backstage/pull/35319 ↗ Show release-note lines
The entity provider also reads users and groups in parallel by default, opening two connections and binds per refresh. Set `disableParallelReads: true` on the provider to retain sequential reads when directory connection limits require it. Connections are closed after each refresh.
github.com/backstage/backstage/releases/tag/v1.57.0TranslationRef values become callable functions
Affectscode that consumes TranslationRef values
Action requiredConsumers must treat TranslationRef values as opaque; they must not clone them or check them for plain-object shape.
Show release-note lines
`TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
github.com/backstage/backstage/releases/tag/v1.57.0Bitbucket Cloud workspace code search now requires user-identifying credentials
AffectsBitbucket Cloud entity provider integrations using workspace code search
Action requiredWorkspace code search requires a user-identifying credential, such as an Atlassian account email as username and an API token, with both read:repository:bitbucket and read:workspace:bitbucket scopes.
Previously, the code search API did not require read:workspace:bitbucket; rejected credentials now send discovery to the source API instead of workspace code search. Adding read:workspace:bitbucket to an API token restores workspace code search.
Evidence“Bitbucket Cloud rejects app passwords, legacy OAuth consumers, and API keys for this API. An API token without `read:workspace:bitbucket` is also rejected with `403`. When that happens, or when code search is not enabled, the provider checks catalog files with the source API instead.” backstage/backstage/pull/36845 ↗ Show release-note lines
The Bitbucket Cloud entity provider now uses the workspace code search API following retirement of the previous endpoint on November 15, 2026. Workspace code search requires a credential that identifies a user, such as an Atlassian account email as `username` with an API `token`, and both `read:repository:bitbucket` and `read:workspace:bitbucket` scopes. App passwords, legacy OAuth consumers, API keys, and API tokens missing the workspace scope are rejected by that API.
github.com/backstage/backstage/releases/tag/v1.57.0Malformed Catalog filters now return HTTP 400
AffectsCatalog query filters using $all, $any, or $not
When a filter object combines one of these operators with other keys, or gives $all or $any a non-array operand, extra keys were silently ignored and count and list queries could interpret the object differently.
Show release-note lines
Malformed predicates that combine `$all`, `$any`, or `$not` with other keys in the same object, or pass non-array operands to `$all` or `$any`, now receive a 400 response instead of silently ignoring parts of the filter. Entity lookups through `entities/by-refs` now match case-insensitively, consistent with the entity reference contract. Contributed by [@chicobento](https://github.com/chicobento) in [#36744](https://github.com/backstage/backstage/pull/36744).
github.com/backstage/backstage/releases/tag/v1.57.0Catalog database gains publication bookkeeping
Affectscatalog backend installations using SQLite, MySQL, or PostgreSQL
On SQLite and MySQL, older instances could overwrite content while retaining a previously assigned generation, so that value did not prove complete change tracking. The upgrade adds a nullable generation column without rewriting existing entities and builds the index concurrently on PostgreSQL.
Show release-note lines
The catalog database upgrade also adds publication bookkeeping and builds an index concurrently on PostgreSQL. The index build scans the catalog table and can exceed deployment startup deadlines on large installations. Review [upgrading large installations](https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md#upgrading-large-installations) for instructions on preparing the column and index before deploying.
Internal publication bookkeeping adds a nullable generation column without
rewriting existing entities. PostgreSQL builds its index concurrently, but still
scans the entire catalog table, even when every generation is null.
The metadata transaction has a five-second lock-wait timeout. If it expires,
startup fails and must retry; repeated failures can cause deployment restart
loops. The concurrent index phase has no imposed timeout and can wait on long
transactions elsewhere in the database, including other plugins using separate
schemas. It may exceed deployment startup deadlines.
github.com/backstage/backstage/releases/tag/v1.57.0Canonical, deduplicated entity references in sign-in resolver user token claims
Affectssetups using sign-in resolvers that issue user token claims containing entity references
Show release-note lines
Sign-in resolvers now issue canonical, deduplicated entity references in user token claims, and `auth logout` correctly revokes the CLI refresh token. A service-authenticated `POST /v1/offline-sessions/revoke` endpoint lets backends revoke all of a user's offline sessions when `auth.experimentalRefreshToken.enabled` is set. Cursor clients are allowed to use CIMD by default, contributed by [@pjohannis](https://github.com/pjohannis) in [#36568](https://github.com/backstage/backstage/pull/36568).
github.com/backstage/backstage/releases/tag/v1.57.0MarkdownContent renderer loads on first use
Affectsapps that use MarkdownContent
Loading the renderer on first use reduces the app startup bundle. Tests that immediately assert on rendered Markdown may need asynchronous queries.
Show release-note lines
- `MarkdownContent` loads its renderer on first use, reducing the app startup bundle. Tests that immediately assert on rendered Markdown may need asynchronous queries.
github.com/backstage/backstage/releases/tag/v1.57.0Backstage CLI commands preserve their exit codes
Affectsautomation that relies on Backstage CLI exit codes(Inferred)
Show release-note lines
- CLI commands preserve their exit codes, and package startup supports repeated `--import` and `--require` flags. Flag support contributed by [@dotboris](https://github.com/dotboris) in [#36647](https://github.com/backstage/backstage/pull/36647).
github.com/backstage/backstage/releases/tag/v1.57.0Legacy app router APIs no longer supported
Affectsapps using RouterBlueprint, the app/root router input, convertLegacyAppOptions({ components: { Router } }), or overrides that install a BrowserRouter
Action requiredRemove overrides that only install a BrowserRouter, move global providers to AppRootWrapperBlueprint, and render page adapters inside lazily loaded page components.
Show release-note lines
`RouterBlueprint`, the `app/root` router input, and `convertLegacyAppOptions({ components: { Router } })` are no longer supported. Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components. Framework navigation destinations must start with `/` and exclude the deployment basename; use a page adapter for path-relative navigation. `useRouteRefParams` now returns only the parameters declared by its route ref, without an undeclared splat parameter. Apps using the old front-end system keep their existing routing setup.github.com/backstage/backstage/releases/tag/v1.57.0routerOptions now accepts only replace and state
Affectscode configuring routerOptions with values other than replace or state
Show release-note lines
Backstage UI routing is configured automatically in Backstage apps. Standalone apps must provide a `useNavigation` hook to `BUIProvider` if they previously relied on automatic React Router integration. `routerOptions` now only accepts `replace` and `state`, and links using `javascript:`, `data:`, or `vbscript:` become inert. See the [routing migration notes](../frontend-system/architecture/60-migrations.md#157) and [page router guide](../frontend-system/building-plugins/10-page-routers.md) for setup and migration examples.
github.com/backstage/backstage/releases/tag/v1.57.0DialogApi.open replaces show and showModal
AffectsExtensions and API implementations using the dialog API(Inferred)
Action requiredUpdate custom extensions and API implementations that use show or showModal; use DialogApi.open with your own dialog presentation and the core.dialog.v2 API reference, and upgrade @backstage/plugin-app alongside @backstage/frontend-plugin-api.
Show release-note lines
- Use `DialogApi.open` with your own dialog presentation instead of `show` or `showModal`, and `IconsApi.icon` instead of `getIcon`. Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`; the API references are now `core.dialog.v2` and `core.icons.v2`.
github.com/backstage/backstage/releases/tag/v1.57.0Icon API now uses IconsApi.icon and core.icons.v2
Affectsextensions and API implementations using the icon API(Inferred)
Action requiredUpgrade @backstage/plugin-app alongside @backstage/frontend-plugin-api.
Show release-note lines
- Use `DialogApi.open` with your own dialog presentation instead of `show` or `showModal`, and `IconsApi.icon` instead of `getIcon`. Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`; the API references are now `core.dialog.v2` and `core.icons.v2`.
github.com/backstage/backstage/releases/tag/v1.57.0Removal of the @backstage/frontend-plugin-api/alpha entry point
Affectsimports from @backstage/frontend-plugin-api/alpha(Inferred)
Action requiredReplace imports from @backstage/frontend-plugin-api/alpha with imports from the main entry point.
The exports retain the same behavior and identity at the main entry point.
Show release-note lines
- Replace imports from `@backstage/frontend-plugin-api/alpha` with imports from the main entry point. The `/alpha` entry point has been removed; its exports retain the same behavior and identity at their new location.
github.com/backstage/backstage/releases/tag/v1.57.0IconBundleBlueprint now requires icon elements
Affectsextensions using IconBundleBlueprint, IconComponent, or Material UI icons in icon bundles
Action requiredUse IconElement instead of IconComponent and supply icon elements to IconBundleBlueprint; for Material UI icons, use <MyIcon fontSize="inherit" />.
Previously, IconBundleBlueprint took icon components, and the IconComponent type was available. Icons passed through convertLegacyAppOptions are still converted automatically, and auth provider icons still accept components.
Show release-note lines
- Use `IconElement` instead of the removed `IconComponent` type. `IconBundleBlueprint` now requires elements such as `icons: { user: <MyIcon /> }` rather than components. For Material UI icons, use `<MyIcon fontSize="inherit" />`. Icons passed through `convertLegacyAppOptions` are converted automatically, and auth provider icons continue to accept components.github.com/backstage/backstage/releases/tag/v1.57.0Specialized app setup moved to the prepare/finalize flow
Affectsapps using createSpecializedApp
Action requiredReplace createSpecializedApp with prepareSpecializedApp(options).finalize(). Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through onFinalized(); advanced.sessionState can be used to reuse a finalized session.
Show release-note lines
- Use `prepareSpecializedApp(options).finalize()` instead of `createSpecializedApp`. Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through `onFinalized()`. Use `advanced.sessionState` to reuse a finalized session, and `ApiBlueprint` extensions to register custom APIs.
github.com/backstage/backstage/releases/tag/v1.57.0Custom APIs registered with ApiBlueprint extensions
Affectsextensions that register custom APIs
Show release-note lines
- Use `prepareSpecializedApp(options).finalize()` instead of `createSpecializedApp`. Apps with sign-in or asynchronous session preparation must render the bootstrap app and subscribe through `onFinalized()`. Use `advanced.sessionState` to reuse a finalized session, and `ApiBlueprint` extensions to register custom APIs.
github.com/backstage/backstage/releases/tag/v1.57.0Custom navigation components now use navItems
Affectscustom navigation components
They previously received a flat items collection; they now access items through navItems.rest(), using item.href and item.title, and render item.icon as a React element.
Show release-note lines
- Custom navigation components now receive `navItems` instead of the flat `items` collection. Use `navItems.rest()`, `item.href`, and `item.title`, and render `item.icon` as a React element.
github.com/backstage/backstage/releases/tag/v1.57.0Analytics and extension middleware import locations changed
Affectsprojects importing the named analytics exports or ExtensionFactoryMiddleware(Inferred)
AnalyticsImplementation, AnalyticsImplementationBlueprint, and AnalyticsImplementationFactory are imported from @backstage/plugin-app-react; ExtensionFactoryMiddleware is imported from @backstage/frontend-app-api.
Show release-note lines
- Import `AnalyticsImplementation`, `AnalyticsImplementationBlueprint`, and `AnalyticsImplementationFactory` from `@backstage/plugin-app-react`, and `ExtensionFactoryMiddleware` from `@backstage/frontend-app-api`.
github.com/backstage/backstage/releases/tag/v1.57.0withApis replaced by function components using useApi
Affectsfrontend-system code using withApis(Inferred)
Action requiredReplace withApis with a function component using useApi.
Show release-note lines
- Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.
github.com/backstage/backstage/releases/tag/v1.57.0Frontend plugin aliases removed
AffectsExtensions using the id, PageTab, or PluginOptions aliases(Inferred)
Action requiredUse FrontendPlugin.pluginId, PageLayoutTab, and CreateFrontendPluginOptions instead of the removed id, PageTab, and PluginOptions aliases.
Before this release, extensions used those aliases in place of the named replacements. After upgrading, the named replacement property and types are used.
Show release-note lines
- Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.
github.com/backstage/backstage/releases/tag/v1.57.0ProgressProps replaced with its existing {} shape
Affectsconsumers using ProgressProps(Inferred)
Show release-note lines
- Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.github.com/backstage/backstage/releases/tag/v1.57.0Ignored anchorOrigin option removed from alert and toast settings
Affectsbuilt-in alert display configurations or toast display props that specify anchorOrigin(Inferred)
These settings accepted anchorOrigin, but the option was ignored.
Show release-note lines
- Remove the ignored `anchorOrigin` option from built-in alert display configuration and toast display props.
github.com/backstage/backstage/releases/tag/v1.57.0FrontendFeature plugins must provide pluginId
Affectsplugins passed as a FrontendFeature that predate the pluginId property
Action requiredPlugins that predate the pluginId property must be rebuilt against a current framework version
Show release-note lines
Plugins passed as a `FrontendFeature` must now provide `pluginId`. Rebuild plugins that predate this property against a current framework version.
github.com/backstage/backstage/releases/tag/v1.57.0Standalone mock types removed
Affectstest code using standalone mock types
Standalone mock types were available before this release. Their types can now be derived from mockApis helpers, for example with ReturnType<typeof mockApis.analytics>.
Show release-note lines
Test apps also use defaults designed for isolation: storage is kept in memory per app, toasts and errors are collected without displaying them, and alerts are no longer replayed to late subscribers. Tests that depend on browser storage, visible notifications, or global error handling need an explicit API implementation. Expanded `mockApis` helpers provide typed mocks and functional fakes for core APIs. Removed standalone mock types can be replaced with types derived from these helpers, such as `ReturnType<typeof mockApis.analytics>`.
github.com/backstage/backstage/releases/tag/v1.57.0Navigation tests now use framework routing for page matching
Affectsnavigation tests with elements that need routing-library context
Action requiredTest elements that need routing-library context must be wrapped in a page adapter.
Show release-note lines
Both render helpers now return an `apis` holder with access to the same Utility API instances used by components, including test overrides. For navigation tests, use `apis.get(coreApis.appHistory)` to access the app history. Page matching uses framework routing; wrap test elements in a page adapter when they need routing-library context. See the [navigation testing guide](../frontend-system/building-plugins/02-testing.md#navigation-and-app-history).
github.com/backstage/backstage/releases/tag/v1.57.0Supported Node.js versions move from 22 and 24 to 24 and 26
AffectsBackstage setups using Node.js 22 or specifying Node.js versions in the root engines.node, CI workflows, or Docker images
Action requiredRoot package.json engines.node set to ^24.15.0 || ^26.13.0, with matching Node.js versions in CI workflows and Docker images; create-app requires Node.js 24.15.0+ or 26.13.0+.
Show release-note lines
The supported Node.js versions are now 24 and 26. Update `engines.node` in your root `package.json` to `^24.15.0 || ^26.13.0`, and check the versions used in your CI workflows and Docker images. Versions of `avsc` before 5.7.8 can break tests on Node.js 26, and `node-gyp` 12.3.0 cannot download headers through a proxy on that version; run `yarn up -R avsc` or `yarn up -R node-gyp` if your lockfile contains the affected versions.
github.com/backstage/backstage/releases/tag/v1.57.0Backstage CLI compilation target raised to ES2024
AffectsBackstage CLI package builds, app bundles, and backend development transforms
Action requiredTypeScript 5.9 or later; for frontend use of ES2024 built-ins, Chrome or Edge 119, Firefox 121, or Safari 17.4 or later
These builds and transforms move from ES2023 to ES2024. Frontend code using ES2024 built-ins has no polyfills.
Show release-note lines
The CLI now compiles for ES2024 and requires TypeScript 5.9 or later. Backstage does not include polyfills, so frontend code using ES2024 APIs such as `Object.groupBy` needs Chrome or Edge 119, Firefox 121, or Safari 17.4 or later. Contributed by [@sebdanielsson](https://github.com/sebdanielsson) in [#36512](https://github.com/backstage/backstage/pull/36512) and [#36509](https://github.com/backstage/backstage/pull/36509).
github.com/backstage/backstage/releases/tag/v1.57.0React 18 required by most frontend packages
Affectsapps using frontend packages, especially React 17 apps and the old front-end system
Action requiredReact 18
The old front-end system core packages keep React 17 in their own peer dependency ranges, but their dependencies require React 18.
Show release-note lines
Most frontend packages now require React 18. The old front-end system core packages retain React 17 in their own peer dependency ranges, but their dependencies include packages that require React 18, so apps using the old system also need to plan the upgrade. See the [React 18 migration guide](../tutorials/react18-migration.md) and [frontend migration notes](../frontend-system/architecture/60-migrations.md#react-17-support-removed).
github.com/backstage/backstage/releases/tag/v1.57.0createGitlabTokenValidator now requires a logger argument
Affectscustom calls to createGitlabTokenValidator
Action requiredCustom callers of createGitlabTokenValidator must supply its new logger argument.
Show release-note lines
For development setups that deliberately accept unauthenticated events, each module provides an explicit `dangerouslyAllowUnauthenticatedEvents: true` option. Custom users of `createGitlabTokenValidator` must also supply its new `logger` argument. See the configuration sections for the [GitHub](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-github/README.md#configuration), [GitLab](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-gitlab/README.md#configuration), and [Azure DevOps](https://github.com/backstage/backstage/blob/master/plugins/events-backend-module-azure/README.md#configuration) modules.
github.com/backstage/backstage/releases/tag/v1.57.0Scaffolder Google Cloud task recovery save failures fixed
Affectstask recovery configured with the Scaffolder Google Cloud module
Action requiredBefore upgrading, grant the backend's Google Cloud credentials storage.objects.list on the task recovery bucket, in addition to the existing object permissions.
When template steps finished in quick succession, snapshots could overwrite the same Google Cloud Storage object, hit its mutation rate limit, and cause task recovery workspace saves to fail. Saves now use separate objects; recovery restores the latest snapshot and supports snapshots from older versions, while older snapshots are cleaned up after successful saves and cleanup failures are logged as warnings.
Evidence“Fixed task recovery workspace saves failing with Google Cloud Storage rate limit errors when template steps finish in quick succession. Each snapshot is saved to a separate object, and recovery continues to support snapshots from older versions.” backstage/backstage/pull/36466 ↗ Show release-note lines
### **BREAKING**: Google Cloud task recovery permissions
The Scaffolder Google Cloud module now stores each task recovery snapshot as a separate object, avoiding storage rate limits when template steps finish in quick succession. Grant the backend's Google Cloud credentials `storage.objects.list` on the task recovery bucket before upgrading, in addition to the existing object permissions. Recovery continues to support snapshots saved by older versions.
github.com/backstage/backstage/releases/tag/v1.57.0Backend HTTP router services add addWebSocketHandler for WebSocket routes
Affectssetups with custom HttpRouterService or RootHttpRouterService implementations, or using backend test utilities
Action requiredCustom implementations of HttpRouterService and RootHttpRouterService must implement addWebSocketHandler.
Show release-note lines
The backend HTTP router services now provide `addWebSocketHandler` for registering WebSocket upgrade routes. Routes require token authentication by default, and browser clients can pass bearer tokens through the WebSocket protocol header. Cookie authentication is not supported. Custom implementations of `HttpRouterService` and `RootHttpRouterService` must implement the new method; the backend test utilities support it too.
github.com/backstage/backstage/releases/tag/v1.57.0Express-only WebSocket upgrade handling moved to router API
Affectsplugins handling WebSocket upgrades only through Express, with the framework's server-level listener active
When the framework's server-level listener is the only one, upgrades not matched through the router receive a 404. Existing server upgrade listeners can coexist during migration, and the router provides addWebSocketHandler to register upgrade routes.
Show release-note lines
The Signals backend uses this API, fixing first connections that previously required an HTTP request before the WebSocket could connect. Existing server upgrade listeners can coexist during migration, but plugins that handle upgrades only through Express, such as the Kubernetes proxy, must migrate to the router API when the framework's server-level listener is active. Otherwise, unmatched upgrades receive a 404 response when it is the only server-level listener. See the [HTTP router service documentation](../backend-system/core-services/http-router.md).
github.com/backstage/backstage/releases/tag/v1.57.0t required in custom TranslationApi snapshots
Affectssetups with custom TranslationApi implementations
Action requiredCustom TranslationApi implementations must provide t in every translation snapshot, including while ready is false, using available messages and language fallbacks.
Show release-note lines
`TranslationRef` values are now callable functions and must be treated as opaque values rather than cloned or checked for plain-object shape. Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks. Titles wait for the initial selected language and retain resolved values during later loads or failures, preserving page state. See the [internationalization guide](../frontend-system/building-plugins/07-internationalization.md).
github.com/backstage/backstage/releases/tag/v1.57.0coreServices and mockServices objects frozen
Affectsruntime mutation of coreServices or mockServices, or spying on mockServices helper objects
These operations were previously supported but are no longer supported. Existing calls and types remain available, and mocks created by the helpers are unaffected.
Show release-note lines
- `coreServices` and `mockServices` are now frozen objects. Existing calls and types remain available, but runtime mutation and spying on the mock service helpers themselves are no longer supported; the mocks they create are unaffected.
github.com/backstage/backstage/releases/tag/v1.57.0OpenAPI generation failures now return non-zero exit codes outside watch mode
AffectsOpenAPI client or server generation via package schema openapi generate
Previously, failures such as package lint failing on generated output could still leave the command with exit code 0. Outside watch mode, it now exits non-zero after the generators settle; watch mode logs errors and continues watching.
Evidence“Outside watch mode they now wrap and rethrow the error, and `generate/index.ts` waits for all running generators to settle before exiting so a failure in one doesn't cut off the other mid-run. Watch mode still logs the error and keeps watching.” backstage/backstage/pull/36854 ↗ Show release-note lines
- OpenAPI client and server generation commands exit with a non-zero status when generation fails, allowing CI to detect failures. Watch mode keeps watching after errors. Contributed by [@aksharprabhudesai](https://github.com/aksharprabhudesai) in [#36854](https://github.com/backstage/backstage/pull/36854).
github.com/backstage/backstage/releases/tag/v1.57.0@backstage/cli-module-package-manager-yarn makes Yarn dependencies optional peers
Affectsinstallations of @backstage/cli-module-package-manager-yarn
Action requiredUntil the upstream issue is fixed, pm verify-patches requires @yarnpkg/cli, @yarnpkg/core, and @yarnpkg/plugin-patch as root development dependencies, plus the resolution "@yarnpkg/core/got": "npm:^11.8.6".
The change avoids an upstream installation failure.
Show release-note lines
- `@backstage/cli-module-package-manager-yarn` makes its Yarn dependencies optional peers to avoid an upstream installation failure. Until fixed upstream, users of `pm verify-patches` must add `@yarnpkg/cli`, `@yarnpkg/core`, and `@yarnpkg/plugin-patch` as root development dependencies, along with the resolution `"@yarnpkg/core/got": "npm:^11.8.6"`.
github.com/backstage/backstage/releases/tag/v1.57.0CodeOwnersProcessor and AnnotateScmSlugEntityProcessor exports removed
Affectsbackends using CodeOwnersProcessor or AnnotateScmSlugEntityProcessor from this package(Inferred)
Action requiredTo retain either processor's behavior, the corresponding community module must be installed in the backend package and registered with backend.add(import('<module-package>')); the old custom processor registration must be removed to avoid registering it twice.
Show release-note lines
## Migrating removed processors
`CodeOwnersProcessor` and `AnnotateScmSlugEntityProcessor` are no longer exported
by this package. Use the corresponding community modules to retain their behavior:
- `CodeOwnersProcessor`: [`@backstage-community/plugin-catalog-backend-module-codeowners`](https://github.com/backstage/community-plugins/tree/main/workspaces/catalog/plugins/catalog-backend-module-codeowners)
- `AnnotateScmSlugEntityProcessor`: [`@backstage-community/plugin-catalog-backend-module-annotate-scm-slug`](https://github.com/backstage/community-plugins/tree/main/workspaces/catalog/plugins/catalog-backend-module-annotate-scm-slug)
Install the module you need in your backend package and register it with
`backend.add(import('<module-package>'))`. Remove your custom registration of the
old processor to avoid registering it twice. If you need to configure a processor
explicitly, follow the replacement module's documentation.github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md