Terminal
Terminal/Skill
Walks through fixing validation errors, schema problems and dry-run surprises in RudderStack data catalog and tracking plan YAML.
By RudderStack
Works with
npx skills add rudderlabs/rudder-agent-skills --skill rudder-instrumentation-debuggingThis skill teaches how to diagnose and fix common validation errors, schema issues, and instrumentation problems when working with RudderStack data catalog and tracking plans.
┌─────────────────┐
│ Error Occurs │
└────────┬────────┘
▼
┌─────────────────┐
│ Identify Type │ ← Validation? Schema? Runtime?
└────────┬────────┘
▼
┌─────────────────┐
│ Locate Source │ ← Which file? Which line?
└────────┬────────┘
▼
┌─────────────────┐
│ Understand Rule │ ← What does the validation expect?
└────────┬────────┘
▼
┌─────────────────┐
│ Fix & Validate │ ← Edit, then rudder-cli validate
└─────────────────┘
Error: data-catalog/events/product-viewed.yaml:15
Referenced property 'urn:rudder:property/proudct_id' not found
Cause: Typo in URN or property doesn't exist.
Fix:
# Wrong
- property: "urn:rudder:property/proudct_id" # Typo!
# Right
- property: "urn:rudder:property/product_id"
Debug steps:
# List all properties to find correct name
ls data-catalog/properties/
# Search for the property
grep -r "product" data-catalog/properties/
Error: Duplicate resource name 'Product Viewed' in kind 'event'
- data-catalog/events/ecommerce.yaml:5
- data-catalog/events/legacy.yaml:12
Cause: Same event name defined in multiple files.
Fix: Remove duplicate or rename one:
# Find duplicates
grep -r "name: \"Product Viewed\"" data-catalog/events/
Error: data-catalog/properties/price.yaml:8
Config 'minLength' is not valid for type 'number'
Cause: Using string config options on a number type.
Fix:
# Wrong
spec:
name: "price"
type: "number"
config:
minLength: 1 # String config!
# Right
spec:
name: "price"
type: "number"
config:
minimum: 0 # Number config
Config options by type:
| Type | Valid Config |
|---|---|
string | minLength, maxLength, pattern, format, enum |
number | minimum, maximum, exclusiveMinimum, exclusiveMaximum |
integer | minimum, maximum, exclusiveMinimum, exclusiveMaximum |
array | items, minItems, maxItems |
object | properties (with required flags) |
boolean | (none) |
Error: Circular reference detected in custom type 'RecursiveType'
RecursiveType -> NestedType -> RecursiveType
Cause: Custom type references itself directly or indirectly.
Fix: Restructure to avoid circular references:
# Wrong: Circular
# RecursiveType references NestedType
# NestedType references RecursiveType
# Right: Flatten or use base types
spec:
name: "ParentType"
config:
properties:
- property: "urn:rudder:property/child_id" # Reference by ID instead
required: true
Error: data-catalog/events/checkout.yaml:7
YAML syntax error: unexpected indent
Cause: Incorrect indentation or YAML formatting.
Fix: Check indentation (use 2 spaces, not tabs):
# Wrong
spec:
name: "Checkout Started"
rules: # Wrong indent!
- property: "..."
# Right
spec:
name: "Checkout Started"
rules: # Correct indent
- property: "..."
Error: Invalid URN format 'property/product_id'
Expected: urn:rudder:<type>/<name>
Cause: Missing urn:rudder: prefix.
Fix:
# Wrong
- property: "property/product_id"
# Right
- property: "urn:rudder:property/product_id"
rudder-cli apply --dry-run -l ./
Dry Run Results:
================
New [event] Checkout Started
Updated [property] product_id
Updated [tracking-plan] Web App Tracking Plan
Deleted [event] Legacy Event
Total: 1 new, 2 updated, 1 deleted
| Status | Meaning | Action |
|---|---|---|
New | Will create in workspace | Verify it's intentional |
Updated | Will modify existing | Review changes |
Deleted | Will remove from workspace | Check if intentional! |
If you see unexpected Deleted entries:
Cause 1: File was accidentally removed
# Check git status
git status
# Restore if needed
git checkout -- data-catalog/events/missing-event.yaml
Cause 2: File excluded from validation path
# Ensure you're validating correct directory
rudder-cli apply --dry-run -l ./data-catalog/ # Might miss tracking-plans/
rudder-cli apply --dry-run -l ./ # Validates everything
Cause 3: Import metadata mismatch
# Check metadata.import.id matches workspace
metadata:
import:
id: "evt_abc123" # Must match workspace resource ID
Dry Run Results:
================
No changes detected.
If you expected changes:
rudder-cli validate -l ./# Validate single file
rudder-cli validate -l ./data-catalog/events/checkout.yaml
# Validate directory
rudder-cli validate -l ./data-catalog/events/
rudder-cli validate -l ./ --verbose
Shows:
# Find what references a property
grep -r "urn:rudder:property/product_id" data-catalog/
See references/error-reference.md for:
# Validate all files
rudder-cli validate -l ./
# Preview changes without applying
rudder-cli apply --dry-run -l ./
# Check workspace connection
rudder-cli workspace info
# Re-authenticate if needed
rudder-cli auth login
# Show detailed validation
rudder-cli validate -l ./ --verbose
| Error | Likely Cause | Quick Fix |
|---|---|---|
not found | Typo in URN | Check spelling, use grep to find |
duplicate | Same name twice | Remove duplicate file |
invalid config | Wrong config for type | Match config to type |
circular reference | Types reference each other | Restructure to avoid loops |
syntax error | Bad YAML | Check indentation, use YAML linter |
unexpected deletion | Missing file | Restore from git or re-import |
no changes | Files not saved | Save files, check directory |
Validate early and often
rudder-cli validate -l ./ # After every change
Use consistent naming
Product Viewed)product_id)product-viewed)Commit before applying
git add .
git commit -m "Update schema"
rudder-cli apply -l ./
Review dry-run output
rudder-cli apply --dry-run -l ./ # Always check first
Keep files organized
data-catalog/
├── events/ # One file per event or group
├── properties/ # One file per domain
└── custom-types/ # One file per type
When debugging with API responses and live events: