> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and resolve common Portal issues including authentication failures, catalog sync errors, and identity provider misconfiguration.

<Tip>
  This guide covers common issues you might encounter when using Spotify Portal
  for Backstage and provides solutions to help you resolve them quickly.
</Tip>

## Authentication Issues

### Authentication misconfiguration

<Note>
  If access is lost due to an authentication misconfiguration, the [recovery mode](../guides/enable-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.
</Note>

### User entities in the catalog

<Note>
  If you receive an error message similar to the one below 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 matches the resolver function's requirements.
</Note>

## Access Control Issues

### Unable to access the Admin area

<Note>
  If the Admin area (`/admin`) is unavailable, make sure that the current user
  is included in the [authorizedUsers configuration
  section](../guides/auth/github/setup-auth#grant-admin-access).
</Note>

## Catalog Issues

### Missing Team

<Note>
  If you are unable to find your team, there could be a few factors:

  1. The software catalog might still be ingesting teams from the 3rd party provider (i.e. GitHub), so it might need some time to process. Try waiting and refreshing if you had just started.

  2. 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.
</Note>

## Additional Troubleshooting Resources

For more specific troubleshooting guides, please refer to:

* [GitHub Integration Troubleshooting](./github-integration)
* [Rate Limiting Issues](./rate-limiting)