# Backstage v1.57.0

2026-11-17 · [Original release notes](https://github.com/backstage/backstage/releases/tag/v1.57.0) · [Full summary](https://ratatosk.io/en/releases/backstage/v1.57.0)

Security 7 · Breaking changes 46 · Deprecations 5 · Important fixes 25 · Enhancements 28 · Other changes 34

## Check before upgrading

### Prerequisites

- **Deprecated front-end APIs removed**: The release also adds further deprecations and calls out custom extensions and API implementations for updates during the upgrade.
  > This release removes several deprecated APIs from the front-end system and introduces further deprecations. Update custom extensions and API implementations when upgrading:
- **Node.js 26 compatibility warnings for `avsc` and `node-gyp`**: `avsc` versions before 5.7.8 can break tests, and `node-gyp` 12.3.0 cannot download headers through a proxy. The note specifies `yarn up -R avsc` or `yarn up -R node-gyp` for lockfiles containing the affected versions.
  > 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.
- **ES2024 frontend APIs require newer browser versions**: Because Backstage provides no polyfills, users' browsers need Chrome or Edge 119, Firefox 121, or Safari 17.4 or later to run this code.
  > 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).
- **Instructions for preparing the PostgreSQL column and index before deployment**
  > 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.

  - Backend package dependency restoration instructions
  - Catalog change-feed API and deletion tracking unavailable: On SQLite and MySQL, writes from older instances during a rolling upgrade can overwrite content while retaining an assigned generation, so a non-null generation does not prove complete change tracking. PostgreSQL triggers track generation assignments for older-instance writes; any future feed would need an explicit rollout activation boundary and initial synchronization strategy.

### Upgrade guide

- **App, plugin, and frontend migration guides**
  > If you are migrating an app, start with the [app migration guide](../frontend-system/building-apps/08-migrating.md). Plugin authors can follow the [plugin migration guide](../frontend-system/building-plugins/05-migrating.md). Apps and plugins already using the front-end system should review the breaking changes below and the [1.57 frontend migration notes](../frontend-system/architecture/60-migrations.md#157).

  - Routing migration notes and page router setup guide
- **Keeping Backstage up to date**
  > We recommend that you keep your Backstage project up to date with this latest release. For more guidance on how to upgrade, check out the documentation for [keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated).

## Security (7)

### Links using `javascript:`, `data:`, or `vbscript:` made inert

- Affects: Apps with links using `javascript:`, `data:`, or `vbscript:`

> 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.

### Backstage CLI refresh token revocation fixed

- Affects: setups using the Backstage CLI `auth logout` command

> 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).

### Backstage UI routing configuration updated

- Affects: Backstage apps and standalone apps using automatic React Router integration

Backstage apps now receive Backstage UI routing configuration automatically. Standalone apps that relied on automatic React Router integration must provide a `useNavigation` hook to `BUIProvider`.

> 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.

### [Security status unclear] Auth backend OAuth service now requires `S256` PKCE

- Affects: clients of the auth backend's OAuth service

The service previously accepted and advertised `plain`; clients using it are now rejected and need to generate SHA-256 challenges. Existing CIMD clients and pre-registered clients with a secret must also use `S256`.

> All clients of the auth backend's OAuth service, including existing CIMD clients and pre-registered clients with a secret, now require Proof Key for Code Exchange (PKCE) with the `S256` challenge method. The `plain` method is no longer accepted or advertised. Update clients that use `plain` to generate SHA-256 challenges. Pre-registered client support and PKCE changes contributed by [@drodil](https://github.com/drodil) in [#36567](https://github.com/backstage/backstage/pull/36567).

### GitHub, GitLab, and Azure DevOps webhook endpoints reject requests without secrets

- Affects: Setups using the GitHub, GitLab, or Azure DevOps events modules' own webhook endpoints
- Additional action: Webhook secrets configured under the relevant module settings: `events.modules.github`, `events.modules.gitlab`, or `events.modules.azureDevOps`; GitHub App secrets are also supported.

Requests without a configured secret receive HTTP 403. GitHub can also use a secret configured per GitHub App; routes configured only through `events.http.topics` remain without a validator.

> The GitHub, GitLab, and Azure DevOps events modules now reject requests to their webhook endpoints with HTTP 403 when no webhook secret is configured. Configure secrets under `events.modules.github`, `events.modules.gitlab`, and `events.modules.azureDevOps` before upgrading; GitHub also supports secrets configured per GitHub App. This applies to the modules' own endpoints; routes configured only through `events.http.topics` still have no validator attached.

### TechDocs S3 connection leak fixed

- Affects: TechDocs served from S3

When a browser navigated away before a file finished loading, the response stream kept its pooled connection; after 50 such disconnects, requests failed with a socket timeout. Early response closes now destroy the S3 stream, preventing this pool exhaustion.

> - TechDocs releases storage connections when browsers disconnect early, including a fix for S3 connection pool exhaustion. Contributed in part by [@lvthillo](https://github.com/lvthillo) in [#36468](https://github.com/backstage/backstage/pull/36468).

### Security fixes for Backstage packages

- Affects: setups using one or more of `@backstage/backend-defaults`, `@backstage/plugin-auth-backend`, `@backstage/plugin-catalog-backend`, `@backstage/plugin-catalog-backend-module-gitlab`, `@backstage/plugin-events-backend-module-azure`, `@backstage/plugin-events-backend-module-github`, `@backstage/plugin-events-backend-module-gitlab`, `@backstage/plugin-scaffolder-backend`, `@backstage/plugin-scaffolder-react`, `@backstage/plugin-techdocs-backend`, `@backstage/plugin-techdocs-backend-module-zensical`, `@backstage/plugin-techdocs-node`, or `@techdocs/cli`

> The following packages have received security fixes:
> - `@backstage/backend-defaults`
> - `@backstage/plugin-auth-backend`
> - `@backstage/plugin-catalog-backend`
> - `@backstage/plugin-catalog-backend-module-gitlab`
> - `@backstage/plugin-events-backend-module-azure`
> - `@backstage/plugin-events-backend-module-github`
> - `@backstage/plugin-events-backend-module-gitlab`
> - `@backstage/plugin-scaffolder-backend`
> - `@backstage/plugin-scaffolder-react`
> - `@backstage/plugin-techdocs-backend`
> - `@backstage/plugin-techdocs-backend-module-zensical`
> - `@backstage/plugin-techdocs-node`
> - `@techdocs/cli`

## Breaking changes (46)

### [No downgrade] Experimental DCR removed from the auth backend

- Affects: auth backend setups using experimental DCR, including those with `auth.experimentalDynamicClientRegistration` configured or DCR clients and sessions in the database
- Action required: CIMD 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.

> 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).

### `useRouteRefParams` returns only declared route parameters

- Affects: code 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.

> `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.

### Extension attachment type replacement

- Affects: code using `ExtensionAttachTo` (Inferred)

Consumers now use `Extension<unknown>['attachTo']`.

> - Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.

### Frontend `useApi` now unwraps promise-valued Utility API refs

- Affects: promise-valued Utility API refs used with `useApi` from `@backstage/frontend-plugin-api`
- Action required: When 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)`.

> ### **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.

### Synchronous mocks for promise-valued APIs accepted

- Affects: tests 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.

> 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.

### Test app helpers now throw on reported creation errors

- Affects: Tests using `renderInTestApp`, `renderTestApp`, or `createExtensionTester`
- Action required: Invalid 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.

> `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).

### Test apps now use per-app in-memory storage

- Affects: test apps that depend on browser storage, visible notifications, global error handling, or alert replay for late subscribers
- Action required: An 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.

> 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>`.

### Production JSON logs gain per-line timestamps

- Affects: setups using production JSON logs
- Action required: Log 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.

> 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.

### LDAP organization ingestion now requests mapped attributes by default

- Affects: LDAP organization entity provider and `LdapOrgReaderProcessor` configurations
- Action required: Custom 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.” https://github.com/backstage/backstage/pull/35319

> 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.

### LDAP entity provider defaults to parallel reads

- Affects: LDAP entity providers connected to directories with connection limits that require sequential reads
- Action required: Set `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.” https://github.com/backstage/backstage/pull/35319

> 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.

### `TranslationRef` values become callable functions

- Affects: code that consumes `TranslationRef` values
- Action required: Consumers must treat `TranslationRef` values as opaque; they must not clone them or check them for plain-object shape.

> `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).

### Bitbucket Cloud workspace code search now requires user-identifying credentials

- Affects: Bitbucket Cloud entity provider integrations using workspace code search
- Action required: Workspace 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.” https://github.com/backstage/backstage/pull/36845

> 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.

### Malformed Catalog filters now return HTTP 400

- Affects: Catalog 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.

> 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).

### Catalog database gains publication bookkeeping

- Affects: catalog 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.

> 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.

### Canonical, deduplicated entity references in sign-in resolver user token claims

- Affects: setups using sign-in resolvers that issue user token claims containing entity references

> 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).

### `MarkdownContent` renderer loads on first use

- Affects: apps 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.

> - `MarkdownContent` loads its renderer on first use, reducing the app startup bundle. Tests that immediately assert on rendered Markdown may need asynchronous queries.

### Backstage CLI commands preserve their exit codes

- Affects: automation that relies on Backstage CLI exit codes (Inferred)

> - 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).

### Legacy app router APIs no longer supported

- Affects: apps using `RouterBlueprint`, the `app/root` router input, `convertLegacyAppOptions({ components: { Router } })`, or overrides that install a `BrowserRouter`
- Action required: Remove overrides that only install a `BrowserRouter`, move global providers to `AppRootWrapperBlueprint`, and render page adapters inside lazily loaded page components.

> `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.

### `routerOptions` now accepts only `replace` and `state`

- Affects: code configuring `routerOptions` with values other than `replace` or `state`

> 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.

### `DialogApi.open` replaces `show` and `showModal`

- Affects: Extensions and API implementations using the dialog API (Inferred)
- Action required: Update 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`.

> - 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`.

### Icon API now uses `IconsApi.icon` and `core.icons.v2`

- Affects: extensions and API implementations using the icon API (Inferred)
- Action required: Upgrade `@backstage/plugin-app` alongside `@backstage/frontend-plugin-api`.

> - 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`.

### Removal of the `@backstage/frontend-plugin-api/alpha` entry point

- Affects: imports from `@backstage/frontend-plugin-api/alpha` (Inferred)
- Action required: Replace 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.

> - 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.

### `IconBundleBlueprint` now requires icon elements

- Affects: extensions using `IconBundleBlueprint`, `IconComponent`, or Material UI icons in icon bundles
- Action required: Use `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.

> - 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.

### Specialized app setup moved to the prepare/finalize flow

- Affects: apps using `createSpecializedApp`
- Action required: Replace `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.

> - 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.

### Custom APIs registered with `ApiBlueprint` extensions

- Affects: extensions that register custom APIs

> - 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.

### Custom navigation components now use `navItems`

- Affects: custom 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.

> - 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.

### Analytics and extension middleware import locations changed

- Affects: projects 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`.

> - Import `AnalyticsImplementation`, `AnalyticsImplementationBlueprint`, and `AnalyticsImplementationFactory` from `@backstage/plugin-app-react`, and `ExtensionFactoryMiddleware` from `@backstage/frontend-app-api`.

### `withApis` replaced by function components using `useApi`

- Affects: frontend-system code using `withApis` (Inferred)
- Action required: Replace `withApis` with a function component using `useApi`.

> - Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.

### Frontend plugin aliases removed

- Affects: Extensions using the `id`, `PageTab`, or `PluginOptions` aliases (Inferred)
- Action required: Use `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.

> - Replace `withApis` with a function component using `useApi`. Use `FrontendPlugin.pluginId`, `PageLayoutTab`, and `CreateFrontendPluginOptions` instead of the removed `id`, `PageTab`, and `PluginOptions` aliases.

### `ProgressProps` replaced with its existing `{}` shape

- Affects: consumers using `ProgressProps` (Inferred)

> - Replace `ExtensionAttachTo` with `Extension<unknown>['attachTo']`, and `ProgressProps` with its existing shape, `{}`.

### Ignored `anchorOrigin` option removed from alert and toast settings

- Affects: built-in alert display configurations or toast display props that specify `anchorOrigin` (Inferred)

These settings accepted `anchorOrigin`, but the option was ignored.

> - Remove the ignored `anchorOrigin` option from built-in alert display configuration and toast display props.

### `FrontendFeature` plugins must provide `pluginId`

- Affects: plugins passed as a `FrontendFeature` that predate the `pluginId` property
- Action required: Plugins that predate the `pluginId` property must be rebuilt against a current framework version

> Plugins passed as a `FrontendFeature` must now provide `pluginId`. Rebuild plugins that predate this property against a current framework version.

### Standalone mock types removed

- Affects: test 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>`.

> 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>`.

### Navigation tests now use framework routing for page matching

- Affects: navigation tests with elements that need routing-library context
- Action required: Test elements that need routing-library context must be wrapped in a page adapter.

> 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).

### Supported Node.js versions move from 22 and 24 to 24 and 26

- Affects: Backstage setups using Node.js 22 or specifying Node.js versions in the root `engines.node`, CI workflows, or Docker images
- Action required: Root `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+.

> 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.

### Backstage CLI compilation target raised to ES2024

- Affects: Backstage CLI package builds, app bundles, and backend development transforms
- Action required: TypeScript 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.

> 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).

### React 18 required by most frontend packages

- Affects: apps using frontend packages, especially React 17 apps and the old front-end system
- Action required: React 18

The old front-end system core packages keep React 17 in their own peer dependency ranges, but their dependencies require React 18.

> 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).

### `createGitlabTokenValidator` now requires a `logger` argument

- Affects: custom calls to `createGitlabTokenValidator`
- Action required: Custom callers of `createGitlabTokenValidator` must supply its new `logger` argument.

> 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.

### Scaffolder Google Cloud task recovery save failures fixed

- Affects: task recovery configured with the Scaffolder Google Cloud module
- Action required: Before 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.” https://github.com/backstage/backstage/pull/36466

> ### **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.

### Backend HTTP router services add `addWebSocketHandler` for WebSocket routes

- Affects: setups with custom `HttpRouterService` or `RootHttpRouterService` implementations, or using backend test utilities
- Action required: Custom implementations of `HttpRouterService` and `RootHttpRouterService` must implement `addWebSocketHandler`.

> 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.

### Express-only WebSocket upgrade handling moved to router API

- Affects: plugins 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.

> 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).

### `t` required in custom `TranslationApi` snapshots

- Affects: setups with custom `TranslationApi` implementations
- Action required: Custom `TranslationApi` implementations must provide `t` in every translation snapshot, including while `ready` is false, using available messages and language fallbacks.

> `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).

### `coreServices` and `mockServices` objects frozen

- Affects: runtime 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.

> - `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.

### OpenAPI generation failures now return non-zero exit codes outside watch mode

- Affects: OpenAPI 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.” https://github.com/backstage/backstage/pull/36854

> - 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).

### `@backstage/cli-module-package-manager-yarn` makes Yarn dependencies optional peers

- Affects: installations of `@backstage/cli-module-package-manager-yarn`
- Action required: Until 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.

> - `@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"`.

### `CodeOwnersProcessor` and `AnnotateScmSlugEntityProcessor` exports removed

- Affects: backends using `CodeOwnersProcessor` or `AnnotateScmSlugEntityProcessor` from this package (Inferred)
- Action required: To 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.

> ## 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.

https://github.com/backstage/backstage/blob/master/plugins/catalog-backend/README.md

## Deprecations (5)

### `AnyApiRef` and `AnyApiFactory` deprecated

- Affects: code using `AnyApiRef` or `AnyApiFactory` (Inferred)
- Removed in: not stated

The aliases remain available for compatibility; `ApiRef` and `ApiFactory` without type arguments are the preferred forms.

> - `AnyApiRef` and `AnyApiFactory` are deprecated in favor of `ApiRef` and `ApiFactory` without type arguments. The deprecated aliases remain available for compatibility.

### Individual core Utility API references deprecated in favor of `coreApis`

- Affects: front-end system setups using core Utility API references (Inferred)
- Removed in: not stated

Existing individual references and the grouped form refer to the same API reference, so existing factories and implementations remain compatible during migration. Provider-specific authentication references remain separate.

> The front-end system now groups its core Utility API references in `coreApis`, imported from `@backstage/frontend-plugin-api`. Access APIs through calls such as `useApi(coreApis.config)`, `useApi(coreApis.identity)`, and `useApi(coreApis.toast)`.
> Individual references with namespace equivalents, such as `configApiRef`, are deprecated. Both forms refer to the same API reference, so existing factories and implementations remain compatible during migration. Provider-specific authentication references remain separate. See [consuming Utility APIs](../frontend-system/utility-apis/03-consuming.md#core-utility-apis) for usage examples and migration guidance.

### TechDocs CLI MkDocs flags deprecated in favor of replacements

- Affects: TechDocs CLI configurations or automation using `--mkdocs-port`, `--mkdocs-config-file-name` or `--mkdocs-parameter-*`
- Removed in: not stated

Using a deprecated flag produces a warning. If its replacement is also set, the deprecated flag is ignored.

> The TechDocs CLI supports Zensical in `serve`, `serve:raw`, and `generate`, including live reload in the preview app. Docker images are now selected per engine, and MkDocs previews use `spotify/techdocs:v1.2.8` rather than `latest`. The `--mkdocs-port`, `--mkdocs-config-file-name`, and `--mkdocs-parameter-*` flags are deprecated in favor of `--engine-port`, `--config-file-name`, and `--parameter-*`. An alpha entry point in `@backstage/plugin-techdocs-node` provides building blocks for additional engines.

### `BitbucketCloudClient.searchCode` deprecated; workspace search method added

- Affects: callers of `BitbucketCloudClient.searchCode` or users needing workspace code search (Inferred)
- Removed in: not stated

The method uses a Bitbucket Cloud endpoint scheduled for removal on 2026-11-15. The workspace code search API requires a user credential with the `read:repository:bitbucket` and `read:workspace:bitbucket` scopes.

> When code search is unavailable or rejects the configured credentials, discovery falls back to checking catalog files through the source API. Adding `read:workspace:bitbucket` to an API token restores workspace code search. `BitbucketCloudClient.searchCode` is deprecated in favor of `searchWorkspaceCode`.

### Deprecation notices for `@backstage/core-components` exports

- Affects: setups using the affected `@backstage/core-components` exports
- Removed in: not stated

The exports remain available in this release. Migration guidance points framework-managed pages with page and sub-page extensions to `PageLayout`, standalone layouts to compositions with `@backstage/ui`, and app-customizable icons to `coreApis.icons`.

> Many `@backstage/core-components` exports now have deprecation notices pointing to Backstage UI replacements or compositions. These include page shells, headers, tabs, links, cards, selectors, avatars, alert displays, and icon wrappers. Existing exports and behavior remain available. Follow each component's migration notice when adapting props, document titles, routing, and layout; these are not all direct import replacements.
> Use page and sub-page extensions with `PageLayout` for framework-managed pages, compose `@backstage/ui` for standalone layouts, and use `coreApis.icons` for app-customizable icons.

## Important fixes (25)

### Case-insensitive `entities/by-refs` lookup fixed

- Affects: catalog lookups through `entities/by-refs`

Previously, a reference with different casing from the stored lowercase reference returned `null` even when the entity existed; it now resolves to that entity.

> 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).

### OIDC token expiration now honors `auth.backstageTokenExpiration`

- Affects: Auth backend OIDC token issuance with `auth.backstageTokenExpiration` configured

Previously, the OIDC service issued tokens with a fixed one-hour lifetime even when the setting specified another duration; it now honors that setting, which defaults to 3600 seconds and allows values from 600 to 86400 seconds.

> OAuth access and ID tokens issued by the auth backend now respect `auth.backstageTokenExpiration` instead of always expiring after one hour. Contributed by [@Retr0-XD](https://github.com/Retr0-XD) in [#35325](https://github.com/backstage/backstage/pull/35325).

### [Silent failure] Empty-page and `NaN` range fix for `useTable` pagination

- Affects: complete-mode `useTable` instances that switch `paginationOptions.type` from `none` to `page` after mounting

Before this fix, that switch could leave the table with no rows and a `NaN - NaN of N` range, without warning. The table now displays the first page.

> Alongside the routing changes described above, `useTable` no longer shows an empty page with a `NaN` range when pagination is enabled after mounting. Contributed by [@GabDug](https://github.com/GabDug) in [#35881](https://github.com/backstage/backstage/pull/35881). See the [BUI changelog](https://ui.backstage.io/changelog) for the full list of updates.

### Cross-plugin Valkey cache key collisions fixed

- Affects: setups using the Valkey cache store (`backend.cache.store: valkey`)

When two plugins used the same cache key, each could read or overwrite the other's value. Plugin-namespaced keys now isolate their caches; values are rebuilt as plugins write, while old entries with a TTL remain until expiration and entries without a TTL or old per-plugin key index sets remain until manually removed.

> - The Valkey cache store now separates keys by plugin. Existing cache values are rebuilt under new keys, and old entries without a time to live need manual cleanup. Contributed by [@pavstev](https://github.com/pavstev) in [#36584](https://github.com/backstage/backstage/pull/36584).

### Toast display no longer replays dismissed toasts

- Affects: apps using the toast display

A toast posted via `ToastApi` could reappear after it was dismissed by the close button or timeout and `ToastDisplay` remounted, such as after a theme switch. Now dismissed toasts are removed from the replay buffer, while non-dismissed toasts remain available for replay.

> - Dismissed toasts no longer reappear when the toast display remounts, such as after a theme change. Contributed by [@abdul-karim-mia](https://github.com/abdul-karim-mia) in [#36813](https://github.com/backstage/backstage/pull/36813).

### Scaffolder task-log redaction compares object properties by key

- Affects: Scaffolder backend task logs for action inputs with secret-dependent object properties and public values

When rendering without secrets omitted a secret-dependent object property, positional comparison could mistake later public values for secrets and mask them; a public URL after a secret token could disappear. Object properties are now compared by key while arrays remain compared by position, keeping public values visible and secret-derived keys and values redacted.

> - Scaffolder task controls retain their chosen visibility after completion, log redaction preserves public values, and custom task permission rules are honored. Contributed by [@ebarault](https://github.com/ebarault) in [#36472](https://github.com/backstage/backstage/pull/36472), [#36477](https://github.com/backstage/backstage/pull/36477), and [#36210](https://github.com/backstage/backstage/pull/36210).

### BUI `SelectWidget` multi-select rendering fixed

- Affects: Software Template forms using the BUI theme with `SelectWidget` fields defined as `type: array`, `uniqueItems: true`, and `items.enum`

These fields previously rendered as single-select, and focus and blur passed raw form values rather than indices to `enumOptionsValueForIndex`. They now allow multiple enum selections, while the single-select path remains unchanged.

> - BUI template forms have clearer array item headings, more accessible item controls, and working enum multi-select fields. Contributed by [@ebarault](https://github.com/ebarault) in [#36469](https://github.com/backstage/backstage/pull/36469), and [@Dasmat13](https://github.com/Dasmat13) in [#36423](https://github.com/backstage/backstage/pull/36423) and [#36331](https://github.com/backstage/backstage/pull/36331).

### DevTools scheduled tasks loading display fixed

- Affects: DevTools scheduled tasks view (Inferred)

After the initial load, switching plugins while tasks were loading could leave the previous plugin’s data visible without a progress indicator. The view now shows progress until loading finishes, then displays the table.

> - DevTools displays backend errors and loading progress for scheduled tasks. Contributed by [@Dasmat13](https://github.com/Dasmat13) in [#36533](https://github.com/backstage/backstage/pull/36533).

### Nested template filename generation fixed on Windows

- Affects: Windows use of `backstage-cli new` with templates containing files in nested subdirectories (Inferred)

Backslashes in relative paths could escape Handlebars braces, leaving `{{extensionName}}` uninterpolated and stripping a path separator, which corrupted generated filenames. The CLI now uses forward slashes for nested template paths, allowing Handlebars to interpolate variables and preserve the intended nested filenames.

> - Package scaffolding preserves existing `CODEOWNERS` content, reuses newer compatible dependency ranges, and fixes corrupted nested filenames on Windows. The Windows fix was contributed by [@HLoc26](https://github.com/HLoc26) in [#35242](https://github.com/backstage/backstage/pull/35242).

### Generated API declaration overwrites fixed

- Affects: setups generating API reference pages with declarations whose names collide by case or declaration kind (Inferred)

Previously, generated API reference pages overwrote declarations when their names collided by case or declaration kind. They now retain those declarations instead.

> - Generated API reference pages no longer overwrite declarations whose names collide by case or declaration kind.

### LDAP provider refresh connections closed after each refresh

- Affects: LDAP entity provider refreshes that open LDAP connections

By default, the provider reads users and groups in parallel, opening two connections and binds per refresh.

> 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.

### Signals backend first WebSocket connection fix

- Affects: setups using the Signals backend

Previously, a first WebSocket connection through the Signals backend required an HTTP request before it could connect.

> 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).

### Bitbucket Cloud catalog discovery switches to workspace code search

- Affects: setups using the Bitbucket Cloud entity provider for catalog discovery (Inferred)

The previous code-search endpoint was retired on November 15, 2026. Workspace code search requires a credential that identifies a user and both `read:repository:bitbucket` and `read:workspace:bitbucket` scopes; if search is unavailable or rejects the credentials, discovery falls back to checking catalog files through the source API while finding the same locations for the same configuration.

> 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.

### PostgreSQL catalog facet and total-count queries sped up

- Affects: PostgreSQL catalog facets and `queryEntities()` total-item counts

On production-scale catalogs, conditional permission policies that produced `$any` or `$not` filters could make these queries take 10–25 seconds or time out; long value lists such as ownership claims also benefited. The queries now use entity-ID set operations and return the same results as before where the previous implementation completed.

> Catalog queries on PostgreSQL are faster when conditional permission policies produce `$any` or `$not` filters, or match fields against long lists of values such as ownership claims. Facet and total count queries also benefit. Contributed in part by [@drodil](https://github.com/drodil) in [#36518](https://github.com/backstage/backstage/pull/36518).

### Cross-tab OAuth refresh race fixed

- Affects: Backstage frontend sessions in browsers with the Web Locks API

Concurrent tabs could refresh the same cookie before a rotated refresh token reached the browser, causing sign-in prompts. With Web Locks support, only one refresh for the same provider endpoint runs at a time across tabs; without it, refreshes can still run concurrently.

> Background OAuth refreshes no longer prompt users to sign in again after transient network failures. Contributed by [@csuich2](https://github.com/csuich2) in [#35003](https://github.com/backstage/backstage/pull/35003). Refresh requests are also coordinated across tabs in browsers with the Web Locks API, avoiding competing refreshes with providers that rotate refresh tokens. Contributed by [@hudsonb](https://github.com/hudsonb) in [#36615](https://github.com/backstage/backstage/pull/36615).

### Test rendering helpers preserve extensions with a `test` plugin

- Affects: test rendering helpers used with a plugin named `test` in `features`

> - Test rendering helpers preserve their test extensions when a plugin named `test` is included in `features`.

### Dynamic backend plugin package resolution fixed

- Affects: setups using dynamic backend plugins, including pnpm `isolated` linker setups and Windows plugins inside the Backstage root

Previously, plugins could not resolve shared backend packages absent from the root `node_modules`; on Windows, plugins inside the Backstage root also could not find the root `node_modules` without `NODE_PATH`. The loader now searches the backend package and its own lookup chain after existing locations, which remain first; with `hoist: false`, it finds only direct dependencies of the backend package and the loader.

> - Dynamic backend plugins can resolve shared packages with the isolated pnpm linker. Contributed by [@sebdanielsson](https://github.com/sebdanielsson) in [#36229](https://github.com/backstage/backstage/pull/36229).

### Scaffolder custom task-rule authorization and filtering fixed

- Affects: Scaffolder backends with registered custom `scaffolder-task` permission rules

When a permission policy condition used a registered custom `scaffolder-task` rule for task authorization or task-list filtering, the routes or filtering returned a 500 instead of applying it. These rules are now evaluated for individual task access and list filtering; registering a rule alone does not grant access unless the permission policy returns a condition that uses it.

> - Scaffolder task controls retain their chosen visibility after completion, log redaction preserves public values, and custom task permission rules are honored. Contributed by [@ebarault](https://github.com/ebarault) in [#36472](https://github.com/backstage/backstage/pull/36472), [#36477](https://github.com/backstage/backstage/pull/36477), and [#36210](https://github.com/backstage/backstage/pull/36210).

### Confluence to Markdown attachment download handling fixed

- Affects: Confluence to Markdown Scaffolder action attachment downloads

When an attachment download failed partway through, the Scaffolder step hung and left the file handle open. Such failures now fail the task with the underlying error, and downloaded files are closed on every path.

> - Confluence attachment download failures now fail the task rather than leaving it hanging, and downloaded files are closed correctly. Contributed by [@rowmanempire](https://github.com/rowmanempire) in [#36745](https://github.com/backstage/backstage/pull/36745).

### Broadcast notification status preservation fixed

- Affects: setups using broadcast notifications in the notifications backend (Inferred)

Marking a broadcast notification read or unread could erase its saved status, while saving or unsaving it could erase its read status. These updates now leave the other status unchanged for each user.

> - Broadcast notifications preserve their read and saved states independently. Contributed by [@FayezBast](https://github.com/FayezBast) in [#36535](https://github.com/backstage/backstage/pull/36535).

### DevTools scheduled tasks view now displays returned errors

- Affects: the DevTools scheduled tasks view (Inferred)

When `useScheduledTasks` returned a backend error, authorization denial (403), or network failure, users saw a misleading “no scheduled tasks” message that could suggest a typo or an empty task list.

> - DevTools displays backend errors and loading progress for scheduled tasks. Contributed by [@Dasmat13](https://github.com/Dasmat13) in [#36533](https://github.com/backstage/backstage/pull/36533).

### Localized PostgreSQL unique-violation fallback fixed in catalog ingestion

- Affects: Catalog ingestion with PostgreSQL localized error messages (`lc_messages`)

When duplicate entity references caused a PostgreSQL unique violation, the fast-insert path rethrew the error instead of retrying with individual updates. It now uses that fallback; SQLite and MySQL message-based detection is unchanged.

> - PostgreSQL unique constraint violations are detected correctly when database error messages are localized, allowing catalog ingestion to fall back to individual updates for duplicate entity references. Contributed by [@harshitsharmaaaa](https://github.com/harshitsharmaaaa) in [#36921](https://github.com/backstage/backstage/pull/36921).

### Backstage CLI start commands now accept repeated `--require` flags

- Affects: multiple `--require` options in `backstage-cli package start` or `backstage-cli repo start`, including backend package `start` scripts (Inferred)

Previously, only one `--require` option was allowed, and `repo start` forwarded only the last option from a backend package's `start` script. Repeated options are now accepted, and `repo start` forwards all of them from the script.

> - 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).

### CLI module transform no longer forces typeless JavaScript to CommonJS

- Affects: Local development loading JavaScript from packages without a `type` field through the CLI's Node.js transform

The transform previously treated those JavaScript files as CommonJS, breaking named imports from ES module entry points. Node.js now detects their format so named imports load correctly; TypeScript files in those packages remain treated as CommonJS.

> - The CLI handles JavaScript ES modules in packages without a `type` field correctly. Contributed by [@vibbix](https://github.com/vibbix) in [#36604](https://github.com/backstage/backstage/pull/36604).

### GitHub URL reader drains failed response bodies

- Affects: setups using the GitHub URL reader

When a failed GitHub request returned a body too large for the stream buffers, the reader left the response incomplete and its socket open until restart, leaking connections and memory. It now drains the body before throwing, so the response completes and the connection is released.

> - The GitHub URL reader releases connections after failed requests with large error bodies, avoiding connection and memory leaks during outages. Contributed by [@dddimcha](https://github.com/dddimcha) in [#36830](https://github.com/backstage/backstage/pull/36830).

## Enhancements (28)

- Routing library adapters for front-end system pages
- Router-independent navigation APIs for plugins
- Stable routing entry point and app history access
- Suspense and error handling at page extension boundaries
- Typed mocks and functional fakes for core APIs
- Test render helpers return an `apis` holder
- Pre-registered OAuth clients in the auth backend (To use: `auth.staticClients`)
- Unauthenticated event configuration for GitHub, GitLab, and Azure DevOps modules (To use: Set `dangerouslyAllowUnauthenticatedEvents: true` under the module configuration to enable unauthenticated events.)
- Token authentication for WebSocket upgrade routes (To use: Use the backend HTTP router service's `addWebSocketHandler` method to register WebSocket upgrade routes.)
- Translated titles for page and sub-page blueprints
- Conditional parameter steps in Software Templates (To use: A `when` condition on a parameter step)
- Viewer-aware filtering for the template list
- Backend offline-session revocation endpoint (To use: `auth.experimentalRefreshToken.enabled` must be set)
- Cursor client IDs added to the default CIMD allowlist (To use: CIMD must be enabled; if `allowedClientIdPatterns` is overridden, it must include `https://cursor.com/oauth/mcp-client.json`.)
- Client certificate credentials for Azure DevOps App Registrations (To use: Configure `ClientCertificate` with `clientId`, `tenantId`, and exactly one of `clientCertificate` (inline PEM including the private key) or `clientCertificatePath`.)
- Static error type guards in `@backstage/errors`
- Broader API reference ID format support
- `beginAt` timestamps for plugin and module startup results
- Dynamic plugins support `FrontendFeatureLoader` exports (To use: The dynamic plugin’s exposed entry point must default-export a `FrontendFeatureLoader`; the loader can select and return frontend features at load time, including nested `FrontendFeatureLoader` values.)
- GitLab branch autocomplete in `RepoBranchPicker` (To use: GitLab Scaffolder backend module, `requestUserCredentials`, and a repository field named `repoUrl`)
- GitHub Scaffolder action for repository ruleset creation (To use: Use the `github:repo:rulesets:create` action in a Software Template to create repository rulesets.)
- GitHub org entity providers can fetch public emails with GitHub Apps (To use: Set `fetchEmailForGithubApps` to `true`; the GitHub App must be able to read user emails.)
- Direct AWS account credential selection for Kubernetes clusters (To use: Set `kubernetes.io/aws-account-id` in the cluster's auth metadata to use that account's credentials directly.)
- Backstage CLI startup commands accept `--import`
- Backstage apps apply the selected color scheme before loading (To use: For existing apps: `theme.js` and the `color-scheme` meta tag and script in `packages/app/public/index.html`.)
- Parsed query strings included in event request validator requests
- Custom content types for request rejection payloads (To use: The optional `contentType` option for non-default content types)
- File URL support in `resolvePackagePath`

## Other changes (34)

- Public APIs for four frontend packages are now stable
- Translated titles wait for initial language selection
- Experimental Zensical engine for TechDocs
- Zensical support in TechDocs CLI and preview live reload
- TechDocs CLI per-engine Docker image defaults
- TechDocs engine building blocks in the `/alpha` entry point
- Bitbucket Cloud entity provider catalog discovery fallback
- OAuth refresh no longer clears sessions after transient network failures
- Azure DevOps URL reader startup warning for Azure DevOps Services personal access tokens
- Header tabs scroll within a single row
- Catalog `EntityNotFound` switches to Backstage UI
- Catalog import pull request preview card switches to Backstage UI
- App backend startup checks load cached frontend asset paths only
- Deferred root element additions no longer remount apps
- Swappable components preserve mounted state across prop changes
- TechDocs table of contents alignment fixed
- Scaffolder task pages preserve button-bar visibility after completion
- BUI array item headings use item titles
- BUI form screen reader announcements and labels improved
- GitLab Scaffolder file handling fixed for failed tree listings
- S3 URL reader avoids re-assuming an account role
- Incremental ingestion no longer fails on repeated entity references
- Catalog placeholder processing waits for reads before reporting errors
- PostgreSQL search indexing skips `tsvector` computation for unchanged documents
- `SearchFilter.Autocomplete` preserves typed text after selection
- World Clock widget switches to Backstage UI components and styles
- Package scaffolding preserves existing `CODEOWNERS` content
- Backstage package scaffolding reuses newer compatible dependency ranges
- Backend plugin migrations resolved relative to their package
- Unhandled-request test failures with MSW 3 fixed in `registerMswTestHooks`
- README guidance for the default catalog backend in created apps
- Old backend catalog router wiring instructions
- Catalog schema migration preserves and repairs indexes
- Documentation for starting the catalog backend standalone or launching the example app

---

Summaries are produced by AI, so they can be wrong, and they are provided without warranty.
