/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 the RudderStack MCP server, connected and signed in. If its tools, such as `list_sources`, are missing, connect the server that is there before adding one. In Claude Code, `claude mcp list` prints each server's name and URL, and a RudderStack server can have any name; the rudder-core plugin's is `plugin:rudder-core:rudderstack`. If one points at `https://mcp.rudderstack.com/bearer-auth-mcp`, the access-token route, keep it: leave the plugin's entry disabled, and check that `RUDDERSTACK_ACCESS_TOKEN` is exported in the shell Claude Code was started from, because that entry signs in with the token, not with `Authenticate`. If `claude mcp list` shows that entry as disabled, enable it in `/mcp` without choosing `Authenticate`. If it shows it as pending approval, as it does for an entry in the project's `.mcp.json` until the user approves it, start Claude Code again and approve it. Otherwise, if one points at `https://mcp.rudderstack.com/mcp`, type `/mcp`, choose it, enable it if it is disabled, and choose `Authenticate`. If none does, run `claude mcp add --scope user --transport http rudderstack https://mcp.rudderstack.com/mcp`, start Claude Code again and authenticate it the same way. In other agents, add an HTTP MCP server with that URL in the agent's MCP settings and sign in. `rudder-mcp-setup` covers both routes in full.

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 misconfigure