Backstage catalog "InputError: entity is invalid" in CI

By Daniel Zoghalchali·Latchkey

Backstage validates every entity against its schema. A catalog-info.yaml that omits apiVersion, kind, or metadata.name, or has the wrong shape, is rejected with an InputError during processing.

What this error means

A catalog validation step fails with "InputError: Malformed envelope, ..." or "the entity ... is invalid" pointing at a missing required field.

InputError: Malformed envelope, /metadata/name is a required field
  at CatalogProcessingEngine ...
# catalog-info.yaml has no metadata.name

Common causes

A required field is missing

apiVersion, kind, or metadata.name is absent, so the entity fails schema validation.

The wrong shape or an invalid value

A field has the wrong type, or metadata.name uses characters the schema does not allow.

How to fix it

Add the required envelope fields

1. Ensure apiVersion, kind, and metadata.name are present.
2. Use a valid name (lowercase, no spaces, allowed characters).
3. Re-run validation.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: example-service
spec:
  type: service
  owner: team-a
  lifecycle: production

Validate entities in CI before merge

Run the backstage-cli validation so malformed entities fail on the pull request, not in production.

yarn backstage-cli repo lint
npx @backstage/cli validate-entity catalog-info.yaml

How to prevent it

• Keep apiVersion, kind, and metadata.name in every entity.
• Use valid name characters and lowercase.
• Validate catalog-info.yaml in CI on every change.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation