Backstage Catalog Processor Entity Missing Fields

In this tutorial, you'll learn about Backstage Catalog Processor Entity Missing Fields. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Entities appear with missing fields or are silently dropped from the Backstage catalog with no error in the UI.

Wrong ❌

// CatalogProcessor implementation
class MyProcessor implements CatalogProcessor {
  getProcessorName() { return 'MyProcessor'; }

  async postProcessEntity(
    entity: Entity,
    _location: LocationSpec,
    emit: CatalogProcessorEmit,
  ): Promise<Entity> {
    // Missing null check - crashes when spec is undefined
    entity.spec.lifecycle = entity.spec.lifecycle || 'production';
    return entity;
  }
}

Wrong Output

TypeError: Cannot read properties of undefined (reading 'lifecycle')
    at MyProcessor.postProcessEntity (processor.ts:12)
Entity 'my-service' was not processed: undefined is not iterable

Right ✅

class MyProcessor implements CatalogProcessor {
  getProcessorName() { return 'MyProcessor'; }

  async postProcessEntity(
    entity: Entity,
    _location: LocationSpec,
    emit: CatalogProcessorEmit,
  ): Promise<Entity> {
    if (!entity.spec) {
      entity.spec = {};
    }
    if (!entity.spec.lifecycle) {
      entity.spec.lifecycle = 'production';
    }
    return entity;
  }
}

Right Output

Processor 'MyProcessor' processed entity 'Component:my-service'
Entity fields enriched: lifecycle -> production

Prevention

• Always null-check entity fields before accessing nested properties in processors.
• Use the catalog processor validation utility: catalogProcessor.validateEntityKinds().
• Add the processor to the correct category (location, entity, or post-Process) in your catalog config.
• Test processors with the backstage-cli catalog:validate command.
• Log processor execution for debugging: ctx.logger?.debug('Processor applied to ...').

DodaTech applies similar defensive patterns across Doda Browser, DodaZIP, and Durga Antivirus Pro infrastructure for production reliability.

Common Mistakes with catalog processor

1. Using foldl instead of foldl' causing stack overflow on large lists
2. Forgetting deriving (Show, Eq) on custom data types needed for debugging
3. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable

These mistakes appear frequently in real-world BACKSTAGE code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

This quick fix is part of the DodaTech infrastructure engineering series. Learn more at DodaTech tutorials.