Backstage just introduced a breaking change that will show up as broken relations and confused processors if you upgrade without preparation: v1.55.0 drops the legacy "relations compatibility mode" and ships catalog-model work that deduplicates model layers. In plain terms: relations are stored and canonicalized differently now, and anything that assumed the old shape — processors, tests, catalog-views, and telemetry — will misbehave.
This isn't a tiny refactor: the repository includes multiple commits aimed at producing a single, canonical representation for catalog entities and their relations. Recent stable patch releases focused on housekeeping items like OAuth/profile normalization and email verification; the 1.55 line is a structural change to how the catalog backend represents and reconciles relationships. If your IDP still runs processors that emit the legacy relation shape or a Scaffolder that caches older template identifiers, the catalog may refuse to reconcile some entities or surface duplicates and ghost entries.
Treat Backstage templates and processors as versioned products. The community signal over the last week is practical: templates are distributed artifacts with versions, caches, and adoption signals you should track. Hardening golden paths means making templates tolerant to catalog-semantic changes and adding instrumentation so failures surface quickly.
Metrics matter here in a non-obvious way. Raw counts (templates used, catalog entities) can hide whether the platform delivers value. Combine DORA-style measures (deployment frequency, lead time, MTTR, change-failure rate) with platform-specific signals — Time-to-First-Deployment (TTFD), Platform NPS, and golden-path adoption — to tie catalog hygiene to business outcomes. If catalog reconciliation silently fails after an upgrade, those dashboards will mislead: deployment frequency can look stable while the set of un-deployable services grows.
What to do now (practical, immediate):
- Lock upgrades in your staging clusters and run v1.55 pre-releases against a full catalog export. Do not promote to production without running processors and Scaffolder flows end-to-end.
- Audit every built-in and custom processor for relation-shape assumptions. Update processors to emit the catalog model's current relation shape and re-run reconciliation. Be prepared to reindex or rebuild parts of your catalog data.
- Version your Scaffolder templates and add telemetry for TTFD and adoption. Track when templates are fetched, which template version was used to scaffold, and whether the resulting repo reaches its first build/deploy pipeline.
This was the right call from the Backstage maintainers: canonicalizing the catalog model reduces long-term complexity and makes plugin behavior more predictable. It would have helped to have a clearer, earlier migration guide, but the net result should be fewer subtle duplicates and less long-term baggage for plugin authors — provided IDPs accept the short-term work of updating processors and cleaning data.
If you're running Backstage at scale, this upgrade is a test of platform maturity: can you coordinate schema migrations, communicate template versioning, and instrument the golden path so regressions are visible? If not, expect a week of tickets and degraded developer experience.
One helpful connection: if you haven't already, review the recent patch notes on OAuth/profile normalization to understand what landed before 1.55, and use that stable baseline when validating upgrades: Backstage v1.54.7: OAuth profile normalization and catalog relations compatibility removal.
Final take: model hygiene is platform hygiene. Backstage cleaning its catalog internals is the right long-term move, but it hands platform teams an operational chore that separates the mature IDPs from the rest. Teams that treat templates as versioned products, add TTFD and Platform NPS to dashboards, and automate processor migrations will win. Everyone else will be fielding late-night Slack threads when service graphs stop resolving.
Sources
- Backstage GitHub Repository (latest commits and tags showing v1.55.0 and recent activity)
- Backstage Releases (v1.54.7 latest release, v1.55.0-next pre-releases, catalog-backend changes)
- Dev-Ex.com – Platform Engineering: Backstage v1.54.7 and catalog model changes recap
- Dev-Ex.com – Backstage catalog-backend breaking refactor removes relations compatibility mode
- Platform Engineering – Five key recommendations for platform teams in 2026 (metrics and golden paths)
- Platform Engineering – Platform engineering maturity in 2026: What the data tells us
- Google Cloud Blog – DevOps & SRE (weekly updates and ‘platform usage trap’ guidance)
- DORA Four Keys GitHub Repository (reference implementation for DORA metrics, archived)