/rudder-instrumentation-debugging

name: rudder-instrumentation-debugging
description: Diagnoses and fixes validation errors, schema issues, and instrumentation problems. Use when debugging validation errors, schema issues, or instrumentation problems
allowed-tools: "Bash(rudder-cli *), Read, Write, Edit"

Instrumentation Debugging

This skill teaches how to diagnose and fix common **validation errors**, **schema issues**, and **instrumentation problems** when working with RudderStack data catalog and tracking plans.

For events sent by the AI SDKs (`ai_*`, `mcp_*`), use `rudder-ai-events-verify`, which checks them against the AI events spec.

Debugging Workflow

┌─────────────────┐
│ 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
└─────────────────┘

Common Validation Errors

Error: Reference Not Found

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

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: Invalid Config for Type

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

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: Invalid YAML Syntax

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: URN Format Invalid

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"

Dry-Run Output Analysis

rudder-cli apply --dry-run -l ./

Understanding Output

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!** |

Unexpected Deletions

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

No Changes Detected

Dry Run Results:
================
No changes detected.

If you expected changes:

• Verify files were saved
• Check you're in the correct directory
• Ensure YAML is valid: `rudder-cli validate -l ./`

Schema Debugging

Validate Specific File

# Validate single file
rudder-cli validate -l ./data-catalog/events/checkout.yaml

# Validate directory
rudder-cli validate -l ./data-catalog/events/

Verbose Output

rudder-cli validate -l ./ --verbose

Shows:

• Files being processed
• Resources found
• Validation rules applied

Check Resource References

# Find what references a property
grep -r "urn