/rudder-destination-debugging

name: rudder-destination-debugging
description: 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.
allowed-tools: "Read, Write, Edit"

Destination Debugging

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.

Requires RudderStack MCP connected. See `rudder-mcp-setup` if not yet configured.

Event Delivery Pipeline

Events travel through four stages before reaching a destination. Each stage can fail independently:

SOURCE SDK
    │  events sent
    ▼
PROCESSOR TRANSFORM
    │  maps event to destination format
    │  applies user transformations
    │  tracking-plan governance (block/log/forward)
    ▼
ROUTER / BATCH
    │  groups events for efficient delivery
    │  respects destination rate limits
    ▼
DATA DELIVERY
    │  sends HTTP request to destination API
    │  parses response code
    ├── 2xx ──► delivered ✓
    ├── 298 ──► filtered (transformation dropped it)
    ├── 299 ──► suppressed (tracking-plan governance)
    ├── 429 ──► throttled → retry with backoff
    ├── 4xx ──► aborted (permanent failure, no retry)
    └── 5xx ──► retryable → auto-retry

Debugging Workflow

                    ┌─────────────────────┐
                    │ Events not at dest? │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼──────────────────┐
              ▼                ▼                  ▼
    Source sending?    Metrics show        Errors present?
    (check source      failures?
     event metrics)    (check dest
                        event metrics)
              │                │                  │
              ▼                ▼                  ▼
    No events at    Events sent but      Get error messages
    source → SDK    not delivered →      → see error
    or connection   check error log      classification
    issue                                below

Step 1 — Confirm events leave the source

Ask Claude: > "Show me event metrics for source \<source-name\> over the last hour"

If source volume is zero: the problem is upstream (SDK not firing, write key wrong, source disabled). Not a destination issue.

Step 2 — Check destination event metrics

Ask Claude: > "Show me event metrics for destination \<dest-name\> — how many succeeded vs failed?"

| Metric | Meaning | |--------|---------| | `delivered` | Accepted by destination API | | `failed` / `aborted` | Permanent failure — need manual fix | | `retried` | Temporary failure — RudderStack retrying automatically | | `filtered` | Dropped by transformation (status 298) | | `suppressed` | Blocked by tracking-plan governance (status 299) |

Step 3 — Read the error messages

Ask Claude: > "What errors is destination \<dest-name\> producing?"

Match the error to the classification table in `references/error-reference.md` to determine the fix.

Step 4 — Inspect the raw event payload

Ask Claude: > "Show me live events flowing through source \<source-name\>"

Compare what you see to what the destination expects. Auth errors, field name mismatches, and type errors often become obvious here.

Error Classification

Every delivery failure has an **error category** and an **error type**. These determine what action you need to take.

By error category

| Category | What it means | Where to look | |----------|--------------|---------------| | `network` | HTTP call to destination API failed | Destination error log, destination status page | | `dataValidation` | Event payload rejected by destination API | Live events — check field names, types, required fields | | `transformation` | User transformation threw or returned bad output | Transformation error log | | `platform` | RudderStack internal error | Contact support; usually transient |

By error type (retry behavior)

| Error type | Retried? | What it means | What to do | |------------|----------|--------------|------------| | `retryable` | Yes, auto | Temporary network/server issue (5xx) | Wait; check destination status page | | `throttled` | Yes, auto with backoff | Destination rate-limited you (429) | Reduce event volume or request higher rate limit | | `aborted` | **No** | Permanent failure (4xx, bad credentials, bad payload) | Fix credentials or event data | | `instrumentation` | No | Event data violates destination schema | Fix SDK call — wrong field type or name | | `configuration` | No | Destination misconfigured in RudderStack | Fix destination settings (API key, URL, etc.) | | `filtered` | n/a | Transformation returned `false` or empty | Check transformation logic |

**Key rule:** If error type is `aborted`, it will never self-heal. You must fix the root cause.

Common Failure Scenarios

Auth failure (401 / 403)

**Symptoms:** High aborted count, errors mention "unauthorized", "invalid token", "forbidden".

**Causes and fixes:**

| Cause | Fix | |-------|-----| | API key expired or rotated | Update destination config with new key | | Wrong account region/URL | Verify base URL in destination settings | | Missing required OAuth scopes | Re-authorize the OAuth connection | | IP allowlist blocking RudderStack | Add RudderStack egress IPs to destination allowlist |

Ask Claude: > "Show me the current config for destination \<dest-name\>"

Then open the destination in the RudderStack dashboard and update the credentials.

Events rejected as bad request (400)

**Symptoms:** High aborted count, errors mention "invalid payload", "required field missing", "unexpected field".

**Root causes:** 1. **Event property has wrong type** — e.g. `revenue` sent as a string `"49.99"` but destination expects a number 2. **Required field missing** — destination API re