> ## 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 Bulk Catalog Ingestion

> Resolve common issues with bulk catalog ingestion — missing organizations, failed pull requests, duplicate components, and provider errors.

This guide covers common issues you might encounter when using bulk catalog ingestion and how to resolve them.

## No Organizations Appear

**Symptom:** The organization selector is empty or missing expected items.

**Common causes:**

* Provider credentials expired or lack permissions
* Provider not properly configured in Portal
* Network connectivity issues

**Solutions:**

<AccordionGroup>
  <Accordion title="GitHub">
    1. **Verify GitHub App installation:**

       * Check if your Portal GitHub App is installed for the organization
       * Ensure the installation hasn't been suspended or revoked

    2. **Check App permissions:**

       * Ensure App has "Metadata: Read" permission minimum
       * For YAML mode, verify "Contents: Write" and "Pull Requests: Write"

    3. **Contact your Portal administrator** to verify backend configuration
  </Accordion>

  <Accordion title="GitLab">
    1. **Verify token permissions:**

       * Check token has "read\_api" scope minimum
       * Verify token hasn't expired
       * For YAML mode, ensure "api" scope is included

    2. **Check group access:**

       * Verify user associated with token has access to the group
       * For private groups, ensure user is a member

    3. **Contact your Portal administrator** to verify backend configuration
  </Accordion>

  <Accordion title="Azure DevOps">
    1. **Verify PAT permissions:**

       * Check PAT has "Project and Team (Read)" scope
       * Verify PAT hasn't expired
       * For YAML mode, ensure "Code (Read & Write)" scope

    2. **Check organization URL:**

       * Verify Portal configuration uses correct org URL
       * Format should be `https://dev.azure.com/{organization}`

    3. **Contact your Portal administrator** to verify backend configuration
  </Accordion>
</AccordionGroup>

## No Repositories Appear

**Symptom:** Selected organization but no repositories show up.

**Common causes:**

* Organization has no repositories
* Repositories are private and credentials lack access
* Repositories already registered in catalog

**Solutions:**

1. **Verify repositories exist:**

   * Check the organization on your source control platform
   * Ensure repositories aren't empty or archived

2. **Check access permissions:**

   * Verify your provider credentials have repository read access
   * For private repositories, ensure proper permissions are granted

3. **Check for duplicates:**
   * Repositories already registered may not appear
   * Try searching the catalog for these repositories first

## Pull Requests Not Created

**Symptom:** Completed ingestion in YAML mode but no Pull Requests/Merge Requests appeared in repositories.

**Common causes:**

* Credentials lack write permissions
* Repository is archived or read-only
* Branch protection blocks automated commits

**Solutions:**

1. **Verify write permissions:**

   * **GitHub:** App needs "Contents: Write" and "Pull Requests: Write"
   * **GitLab:** Token needs "api" scope
   * **Azure DevOps:** PAT needs "Code (Read & Write)"

2. **Check repository status:**

   * Ensure repository isn't archived
   * Verify repository allows writes

3. **Review branch protection:**

   * Check if branch protection rules block the Portal from creating Pull Requests
   * Contact your repository admin to allow Portal App commits

4. **Contact your Portal administrator** if issues persist

## Entities Don't Appear in Catalog

**Symptom:** Merged Pull Request/completed ingestion but entities still don't appear in catalog.

**Common causes:**

* Catalog processing still in progress
* YAML validation errors
* Missing required entity fields

**Solutions:**

1. **Wait for processing:**

   * Initial processing can take 1-5 minutes
   * Refresh the catalog page and check again

2. **Check for validation errors:**

   * Navigate to Catalog Settings in Portal
   * Look for processing errors or warnings
   * Review error messages for specific issues

3. **Verify required fields:**
   * Ensure `catalog-info.yaml` includes all required fields:
     * `apiVersion: backstage.io/v1alpha1`
     * `kind: Component`
     * `metadata.name`
     * `spec.type`
     * `spec.lifecycle`
     * `spec.owner`

## Invalid YAML Errors

**Symptom:** Catalog Settings shows "Invalid YAML" for your `catalog-info.yaml` file.

**Common syntax errors:**

### Indentation Issues

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
# ❌ Wrong
metadata:
name: my-service

# ✅ Correct
metadata:
  name: my-service
```

### Missing Required Fields

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
# ❌ Wrong - missing owner
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
spec:
  type: service
  lifecycle: production

# ✅ Correct
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
spec:
  type: service
  lifecycle: production
  owner: platform-team
```

**Solutions:**

1. **Use a YAML validator:**

   * Copy your YAML to [yamllint.com](http://www.yamllint.com/)
   * Check for syntax errors before committing

2. **Copy from a working example:**
   * Find a similar entity in your catalog
   * View its `catalog-info.yaml` and use it as a template

## Owner Not Found

**Symptom:** Entity created but shows "Owner: unknown" or error about invalid owner reference.

**Common causes:**

* Owner team/user doesn't exist in catalog
* Owner name doesn't match catalog entity format

**Solutions:**

1. **Ensure owner entity exists:**

   * For teams, check that a Group entity exists in the catalog
   * For users, check that a User entity exists

2. **Match entity name format:**

   * Use lowercase with hyphens
   * Example: "Platform Team" should be `platform-team`

3. **Use correct owner reference format:**
   ```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
   spec:
     owner: group:default/platform-team  # Full reference
     # or
     owner: platform-team  # Short form (assumes group kind)
   ```

## Getting Help

If you've tried these solutions and still have issues:

1. Check Catalog Settings for specific error messages
2. Contact your Portal administrator with:
   * Error messages from Catalog Settings
   * Steps to reproduce the issue
   * Which provider you're using (GitHub/GitLab/Azure DevOps)
   * Which management mode you selected (Portal vs YAML)