View all articles

Why am I seeing an error message on the DX tab in Spotify Backstage?

This error occurs when the DX tab cannot load the matching entity from the DX catalog. The DX Backstage backend plugin is deprecated and is not required. Do not install it to create a schema or to sync catalog data.

Sync Backstage entities into DX with the Catalog API, then confirm the frontend plugin can reach the DX Web API with the correct entity identifier.

Confirm the frontend plugin configuration

The DX tab is powered by the DX Backstage frontend plugin. It calls the DX Web API through a Backstage proxy. Confirm the following:

  1. Generate an API token on the Web API Keys page that includes the catalog:read scope.
  2. Configure a /dx-web-api proxy in app-config.yaml that targets https://api.getdx.com and sends that token as a Bearer header.
proxy:
  endpoints:
    "/dx-web-api":
      target: https://api.getdx.com
      headers:
        Authorization: Bearer ${DX_WEB_API_TOKEN}
      allowedHeaders:
        - X-Client-Type
        - X-Client-Version

For Scorecards and Tasks routes, datafeed charts, and the rest of the frontend setup, see the frontend plugin README.

Confirm the entity identifier

Scorecards and Tasks components require an entityIdentifier prop that matches the identifier of a catalog entity in DX. If you use the Backstage catalog, use Backstage’s useEntity hook to map or construct that identifier.

If your Backstage entity name matches your DX entity identifier, pass entity.metadata.name. Otherwise, derive the identifier from Backstage entity metadata before passing it in.

Sync Backstage entities into DX

The frontend plugin reads catalog data from DX. It does not import Backstage catalog data into DX.

If the entity does not exist in DX, create or update it with catalog.entities.upsert or catalog.entities.create. Use the same identifier the frontend plugin passes as entityIdentifier.

You can verify the entity exists with catalog.entities.info. For the full set of Catalog API methods, see Web API methods.

If the error persists after these checks, contact DX support with your logs.