Skip to main content

Troubleshooting Bulk Catalog Ingestion

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:

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

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

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

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​

# ❌ Wrong
metadata:
name: my-service

# ✅ Correct
metadata:
  name: my-service

Missing Required Fields​

# ❌ 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
    • 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:

    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)