Skip to main content

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.

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:
  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
  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
  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)