rudder-destination-debugging

Name: rudder-destination-debugging
Author: rudderlabs

18stars0forks

How to install rudder-destination-debugging?

rudderlabs/rudder-agent-skills/rudder-destination-debugging

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-destination-debugging

Installs into the current project.

Summary

Diagnoses why events are failing, dropping, or not arriving at a destination. Use when events are missing from a destination, seeing high error rates, getting auth failures, or events are stuck retrying.

Files · 1

View on GitHub

SKILL.md

1	# Destination Debugging
2
3	This skill teaches how to diagnose and fix event delivery failures between RudderStack and a destination — covering dropped events, auth errors, rate limiting, transformation filters, and warehouse sync failures.
4
5	Requires RudderStack MCP connected. See `rudder-mcp-setup` if not yet configured.
6
7	## Event Delivery Pipeline
8
9	Events travel through four stages before reaching a destination. Each stage can fail independently:
10
11	```
12	SOURCE SDK
13	│ events sent
14	▼
15	PROCESSOR TRANSFORM
16	│ maps event to destination format
17	│ applies user transformations
18	│ tracking-plan governance (block/log/forward)
19	▼
20	ROUTER / BATCH
21	│ groups events for efficient delivery
22	│ respects destination rate limits
23	▼
24	DATA DELIVERY
25	│ sends HTTP request to destination API
26	│ parses response code
27	├── 2xx ──► delivered ✓
28	├── 298 ──► filtered (transformation dropped it)
29	├── 299 ──► suppressed (tracking-plan governance)
30	├── 429 ──► throttled → retry with backoff
31	├── 4xx ──► aborted (permanent failure, no retry)
32	└── 5xx ──► retryable → auto-retry
33	```
34
35	## Debugging Workflow
36
37	```
38	┌─────────────────────┐
39	│ Events not at dest? │
40	└──────────┬──────────┘
41	│
42	┌────────────────┼──────────────────┐
43	▼ ▼ ▼
44	Source sending? Metrics show Errors present?
45	(check source failures?
46	event metrics) (check dest
47	event metrics)
48	│ │ │
49	▼ ▼ ▼
50	No events at Events sent but Get error messages
51	source → SDK not delivered → → see error
52	or connection check error log classification
53	issue below
54	```
55
56	### Step 1 — Confirm events leave the source
57
58	Ask Claude:
59	> "Show me event metrics for source \<source-name\> over the last hour"
60
61	If source volume is zero: the problem is upstream (SDK not firing, write key wrong, source disabled). Not a destination issue.
62
63	### Step 2 — Check destination event metrics
64
65	Ask Claude:
66	> "Show me event metrics for destination \<dest-name\> — how many succeeded vs failed?"
67
68	\| Metric \| Meaning \|
69	\|--------\|---------\|
70	\| `delivered` \| Accepted by destination API \|
71	\| `failed` / `aborted` \| Permanent failure — need manual fix \|
72	\| `retried` \| Temporary failure — RudderStack retrying automatically \|
73	\| `filtered` \| Dropped by transformation (status 298) \|
74	\| `suppressed` \| Blocked by tracking-plan governance (status 299) \|
75
76	### Step 3 — Read the error messages
77
78	Ask Claude:
79	> "What errors is destination \<dest-name\> producing?"
80
81	Match the error to the classification table in `references/error-reference.md` to determine the fix.
82
83	### Step 4 — Inspect the raw event payload
84
85	Ask Claude:
86	> "Show me live events flowing through source \<source-name\>"
87
88	Compare what you see to what the destination expects. Auth errors, field name mismatches, and type errors often become obvious here.
89
90	## Error Classification
91
92	Every delivery failure has an error category and an error type. These determine what action you need to take.
93
94	### By error category
95
96	\| Category \| What it means \| Where to look \|
97	\|----------\|--------------\|---------------\|
98	\| `network` \| HTTP call to destination API failed \| Destination error log, destination status page \|
99	\| `dataValidation` \| Event payload rejected by destination API \| Live events — check field names, types, required fields \|
100	\| `transformation` \| User transformation threw or returned bad output \| Transformation error log \|
101	\| `platform` \| RudderStack internal error \| Contact support; usually transient \|
102
103	### By error type (retry behavior)
104
105	\| Error type \| Retried? \| What it means \| What to do \|
106	\|------------\|----------\|--------------\|------------\|
107	\| `retryable` \| Yes, auto \| Temporary network/server issue (5xx) \| Wait; check destination status page \|
108	\| `throttled` \| Yes, auto with backoff \| Destination rate-limited you (429) \| Reduce event volume or request higher rate limit \|
109	\| `aborted` \| No \| Permanent failure (4xx, bad credentials, bad payload) \| Fix credentials or event data \|
110	\| `instrumentation` \| No \| Event data violates destination schema \| Fix SDK call — wrong field type or name \|
111	\| `configuration` \| No \| Destination misconfigured in RudderStack \| Fix destination settings (API key, URL, etc.) \|
112	\| `filtered` \| n/a \| Transformation returned `false` or empty \| Check transformation logic \|
113
114	Key rule: If error type is `aborted`, it will never self-heal. You must fix the root cause.
115
116	## Common Fa

People who liked this also viewed

6 picks

Type

rudder-destination-debugging

18stars0forks

View on GitHub

How to install rudder-destination-debugging?

rudderlabs/rudder-agent-skills/rudder-destination-debugging

$npx -y skills add rudderlabs/rudder-agent-skills --skill rudder-destination-debugging

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Destination Debugging
2
3	This skill teaches how to diagnose and fix event delivery failures between RudderStack and a destination — covering dropped events, auth errors, rate limiting, transformation filters, and warehouse sync failures.
4
5	Requires RudderStack MCP connected. See `rudder-mcp-setup` if not yet configured.
6
7	## Event Delivery Pipeline
8
9	Events travel through four stages before reaching a destination. Each stage can fail independently:
10
11	```
12	SOURCE SDK
13	│ events sent
14	▼
15	PROCESSOR TRANSFORM
16	│ maps event to destination format
17	│ applies user transformations
18	│ tracking-plan governance (block/log/forward)
19	▼
20	ROUTER / BATCH
21	│ groups events for efficient delivery
22	│ respects destination rate limits
23	▼
24	DATA DELIVERY
25	│ sends HTTP request to destination API
26	│ parses response code
27	├── 2xx ──► delivered ✓
28	├── 298 ──► filtered (transformation dropped it)
29	├── 299 ──► suppressed (tracking-plan governance)
30	├── 429 ──► throttled → retry with backoff
31	├── 4xx ──► aborted (permanent failure, no retry)
32	└── 5xx ──► retryable → auto-retry
33	```
34
35	## Debugging Workflow
36
37	```
38	┌─────────────────────┐
39	│ Events not at dest? │
40	└──────────┬──────────┘
41	│
42	┌────────────────┼──────────────────┐
43	▼ ▼ ▼
44	Source sending? Metrics show Errors present?
45	(check source failures?
46	event metrics) (check dest
47	event metrics)
48	│ │ │
49	▼ ▼ ▼
50	No events at Events sent but Get error messages
51	source → SDK not delivered → → see error
52	or connection check error log classification
53	issue below
54	```
55
56	### Step 1 — Confirm events leave the source
57
58	Ask Claude:
59	> "Show me event metrics for source \<source-name\> over the last hour"
60
61	If source volume is zero: the problem is upstream (SDK not firing, write key wrong, source disabled). Not a destination issue.
62
63	### Step 2 — Check destination event metrics
64
65	Ask Claude:
66	> "Show me event metrics for destination \<dest-name\> — how many succeeded vs failed?"
67
68	\| Metric \| Meaning \|
69	\|--------\|---------\|
70	\| `delivered` \| Accepted by destination API \|
71	\| `failed` / `aborted` \| Permanent failure — need manual fix \|
72	\| `retried` \| Temporary failure — RudderStack retrying automatically \|
73	\| `filtered` \| Dropped by transformation (status 298) \|
74	\| `suppressed` \| Blocked by tracking-plan governance (status 299) \|
75
76	### Step 3 — Read the error messages
77
78	Ask Claude:
79	> "What errors is destination \<dest-name\> producing?"
80
81	Match the error to the classification table in `references/error-reference.md` to determine the fix.
82
83	### Step 4 — Inspect the raw event payload
84
85	Ask Claude:
86	> "Show me live events flowing through source \<source-name\>"
87
88	Compare what you see to what the destination expects. Auth errors, field name mismatches, and type errors often become obvious here.
89
90	## Error Classification
91
92	Every delivery failure has an error category and an error type. These determine what action you need to take.
93
94	### By error category
95
96	\| Category \| What it means \| Where to look \|
97	\|----------\|--------------\|---------------\|
98	\| `network` \| HTTP call to destination API failed \| Destination error log, destination status page \|
99	\| `dataValidation` \| Event payload rejected by destination API \| Live events — check field names, types, required fields \|
100	\| `transformation` \| User transformation threw or returned bad output \| Transformation error log \|
101	\| `platform` \| RudderStack internal error \| Contact support; usually transient \|
102
103	### By error type (retry behavior)
104
105	\| Error type \| Retried? \| What it means \| What to do \|
106	\|------------\|----------\|--------------\|------------\|
107	\| `retryable` \| Yes, auto \| Temporary network/server issue (5xx) \| Wait; check destination status page \|
108	\| `throttled` \| Yes, auto with backoff \| Destination rate-limited you (429) \| Reduce event volume or request higher rate limit \|
109	\| `aborted` \| No \| Permanent failure (4xx, bad credentials, bad payload) \| Fix credentials or event data \|
110	\| `instrumentation` \| No \| Event data violates destination schema \| Fix SDK call — wrong field type or name \|
111	\| `configuration` \| No \| Destination misconfigured in RudderStack \| Fix destination settings (API key, URL, etc.) \|
112	\| `filtered` \| n/a \| Transformation returned `false` or empty \| Check transformation logic \|
113
114	Key rule: If error type is `aborted`, it will never self-heal. You must fix the root cause.
115
116	## Common Fa

People who liked this also viewed

6 picks

Type