rudder-instrumentation-debugginglisted
Install: claude install-skill rudderlabs/rudder-agent-skills
# 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:**
```yaml
# Wrong
- property: "urn:rudder:property/proudct_id" # Typo!
# Right
- property: "urn:rudder:property/product_id"
```
**Debug steps:**
```bash
# 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'
-