Skip to main content

Troubleshooting

Authentication misconfiguration​

If access is lost due to an authentication misconfiguration, the recovery mode can be enabled.

Once signed in using the root user, make sure that the configuration applied is in a functioning state by signing in using the configured authentication provider, keeping the recovery mode enabled until a successful sign in has been achieved.

User entities in the catalog​

If an error message similar to the one below is received when trying to use a newly configured authentication provider, the current provider's sign in resolver function is unable to locate a matching user in the catalog.

Login failed; caused by Error: Failed to sign-in, unable to resolve user identity

Make sure that a user is present in the catalog that is matching the resolver functions requirements.

Unable to visit the Config Manager​

If the Config Manager (/config-manager) is unavailable, make sure that the current user is included in the authorizedUsers configuration section.

Connection to the database is lost​

Portal is dependent on connecting to its database. If errors similar to Error: Failed to connect to the database... are present in the logs, make sure that the database credentials and connectivity to the database is working properly.

Rolling back a broken config change​

Note: This does not guarantee to set a working config to be active. This command may need to be run until a working config version is found and rolled back to.

If you make a change to the config that has resulted in the application failing to work as expected, you can rollback the change via your Postgres database.

  1. Connect to your database using the environment variable values passed into the Portal container
psql -h $PORTAL_DATABASE_HOST -p $PORTAL_DATABASE_PORT -U $PORTAL_DATABASE_USER -d backstage_plugin_config-manager
# Use the value of PORTAL_SECRET_DATABASE_PASSWORD as password when prompted
  1. Run the following command to set the config prior to the last change as active
DO $$
DECLARE
  previous_active_id INT;
BEGIN
  SELECT MAX(id) INTO previous_active_id
  FROM config
  WHERE id < (SELECT MAX(id) FROM config WHERE is_active = true);

  UPDATE config SET is_active = FALSE WHERE is_active = TRUE;
  UPDATE config SET is_active = TRUE WHERE id = previous_active_id;
  RAISE NOTICE 'Updated active config to id: %', previous_active_id;
END $$;

Missing Team​

If you are unable to find your team, there could be a few factors. The first is that the software catalog is still ingesting teams from the 3rd party provider (i.e. Github), so it might still need some time to process. Try waiting and refreshing if you had just started.

If you are still unable to find your team, you either need to create that team in the 3rd party source or ask an administrator to create it for you. Once updated, you should be able to view your team within 1 hour.

Handling multiple representations of the same logical team in Backstage​

Why do I see multiple entries for what I believe is the same team in the catalog-onboarding-wizard?​

This situation arises due to the way teams are represented and managed across different platforms. Here’s a breakdown of the issue:

  • Logical Team: This is the real-life group of individuals working together.
  • GitHub Team: This is the representation of a logical team within GitHub, managed under specific GitHub organizations.
  • Backstage Team: This is the representation of a logical team within Backstage, inferred from third-party sources like GitHub.

When you use the Setup Wizard to connect your Portal with GitHub/GHE, you select the GitHub organizations relevant to your operations. During this process, the catalog-onboarding-wizard pulls team data from the chosen GitHub organizations via the GitHub API. The names of these teams are then constructed in the format: GithubOrgName/GithubTeamName.

For instance, a logical team named “Chipmunks” could exist in multiple GitHub organizations. Consequently, it might appear in different forms such as:

  • backstage/chipmunks
  • chipmunks/chipmunks
  • tools/chipmunks

When these are ingested into Backstage, each representation is treated as a distinct team. This multiplicity can lead to confusion during the component onboarding process, particularly when determining the “owner” in the catalog-info.yaml files, as the system prompts you to select from multiple similar entries.

How should I handle multiple Backstage team entries that represent the same logical team?​

Here’s our recommended approach to navigate this scenario:

  1. Identification: Recognize that the multiple entries you see are due to the logical team being represented across different GitHub organizations.
  2. Selection: Choose the most appropriate team representation based on the context of your project or component. Typically, this would be the team within the GitHub organization that is most relevant to your current work.
  3. Consistency: For future onboarding processes, try to consistently select the same team representation to avoid fragmentation where different components belong to different Backstage teams, even though they pertain to the same logical team.

What if I make a mistake and select different Backstage teams for the same logical team?​

We understand that this can happen, and it’s a known issue we are actively working to resolve. For now, you can manage this situation by:

  1. Documentation: Keep a record of the team selections you make during the onboarding process to ensure consistency.
  2. Review: Periodically review the catalog-info.yaml files to identify and correct any inconsistencies in team ownership.

Is there a long-term solution to this issue?​

We are aware of this challenge and are working towards a more robust solution. In future updates, we aim to provide improved mechanisms for recognizing and consolidating logical teams across different GitHub organizations, thereby reducing the confusion and effort required to manage team ownership accurately.

Replacing GitHub expired personal access token​

If your GitHub personal access token has expired, you can replace it with the following steps:

  1. Visit https://github.com/settings/tokens
  2. Select the token you're using for your Portal instance
  3. Select "Regenerate token"

GitHub regenerate token

  1. Confirm the expiration of your token and select "Regenerate token"
  2. Copy and store your token securely
  3. In Spotify Portal, navigate to <baseURL>/config-manager/app#root.integrations.github__title

Config Manager Github Token

  1. In the "token" field, paste your new token and select "Save Changes"