Fix Backstage Entity YAML – Entity Not Registered or Invalid

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: A cool service

You commit and push. The Backstage catalog import succeeds, but the entity shows as "Unknown" in the UI with no type or lifecycle.

Logs:

Validation error: must have required property 'spec.type'
Validation error: must have required property 'spec.lifecycle'

## Right ✅

```yaml
# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  title: My Service
  description: A cool service that handles user authentication
  annotations:
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: my-org/my-service
tags:
    - auth
    - <a href="/programming-languages/typescript/">TypeScript</a>
spec:
  type: service
  lifecycle: production
  owner: team-auth
  system: auth-system
  dependsOn:
    - component:shared-db
  providesApis:
    - my-service-api

After pushing, the entity appears:

📁 my-service
  Type: service
  Lifecycle: production
  Owner: team-auth
  System: auth-system
  API: my-service-api

**Full entity kinds:**

| Kind | Required spec fields |
|------|---------------------|
| `Component` | `type`, `lifecycle`, `owner` |
| `API` | `type`, `lifecycle`, `owner`, `definition` |
| `Resource` | `type`, `owner` |
| `System` | `owner` |
| `Domain` | `owner` |
| `Group` | `type`, `children` |
| `User` | (minimal — name only) |

## Root Cause

Backstage enforces a JSON Schema validation for every entity kind. Missing required `spec` fields (like `type`, `lifecycle`, `owner`) cause the entity to be rejected by the catalog processor.

## Prevention

- Use the **catalog-info.yaml** template in VSCode with the Backstage extension for auto‑completion.
- Run `yarn backstage-cli validate` locally before pushing.
- Check the catalog logs: `kubectl logs -l app=backstage-catalog` or `docker logs backstage-backend`.
- Keep `catalog-info.yaml` in the root of each Repository — Backstage discovery finds it automatically.


## Common Mistakes with entity yaml

1. **Forgetting `deriving (Show, Eq)` on custom data types needed for debugging**
2. **Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable**
3. **Using `head` and `tail` instead of pattern matching, causing runtime errors on empty lists**

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

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: What happens if I push an invalid YAML?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Backstage logs the validation error and skips the entity. Fix the YAML and push again — the catalog re‑processes on the next ingestion cycle.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: Can I have multiple entities in one file?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Yes — separate with <code>---</code> (YAML document separator):</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">```yaml</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><hr />
<h2 id="kind-component">kind: Component
...</h2><p>kind: API
...</p>
<pre><code></code></pre></div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: How do I reference another entity?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Use <code>relationRef</code> format: <code>component:my-service</code>, <code>api:my-api</code>, <code>group:team-auth</code>.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">**Q: What if my entity references a system that doesn't exist yet?**</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>A: Backstage still ingests it but logs a warning. Create the dependency entities first for a clean graph.</p>
</div></details>

---

*Entity modelling is covered in the [DodaTech Backstage Catalog course](https://dodatech.com/courses/backstage).*