sentry-common-errors

What this skill does

# Sentry Common Errors

## Overview

Diagnose and fix the most frequently encountered Sentry SDK integration issues across Node.js, browser, and Python environments. Covers DSN validation, missing events, source map failures, rate limiting, SDK initialization ordering, serverless flush patterns, CORS configuration, and environment tagging.

## Prerequisites

- Sentry SDK installed (`@sentry/node` v8+, `@sentry/browser` v8+, or `sentry-sdk` for Python)
- Access to Sentry dashboard with project admin or member role
- Application logs available for inspection
- `sentry-cli` installed for source map and release operations

## Instructions

### Step 1 — Detect the installed SDK and current configuration

!`npm list @sentry/node @sentry/browser @sentry/react @sentry/nextjs 2>/dev/null | head -10 || echo "No Node.js Sentry SDK found"`

!`python3 -c "import sentry_sdk; print(f'sentry-sdk {sentry_sdk.VERSION}')" 2>/dev/null || echo "No Python sentry-sdk found"`

!`command -v sentry-cli >/dev/null && sentry-cli --version || echo "sentry-cli not installed"`

Grep the project for Sentry initialization to identify the current configuration:

```bash
grep -rn "Sentry.init\|sentry_sdk.init" --include="*.ts" --include="*.js" --include="*.mjs" --include="*.py" . 2>/dev/null | head -20
```

### Step 2 — DSN not set or invalid DSN format

The DSN (Data Source Name) tells the SDK where to send events. Format: `https://<public-key>@<org>.ingest.sentry.io/<project-id>`

**Symptoms:** No events arrive. SDK silently does nothing. `debug: true` shows "No DSN provided."

```typescript
// WRONG — DSN is undefined because env var is missing or misspelled
Sentry.init({
  dsn: process.env.SENTRI_DSN, // Typo in env var name
});

// CORRECT — validate DSN is present before init
const dsn = process.env.SENTRY_DSN;
if (!dsn) {
  console.error('SENTRY_DSN environment variable is not set');
  process.exit(1);
}
Sentry.init({
  dsn: dsn.trim(),
  debug: true, // Enable during troubleshooting
});
```

**Python equivalent:**

```python
import os, sentry_sdk

dsn = os.environ.get("SENTRY_DSN")
if not dsn:
    raise RuntimeError("SENTRY_DSN not set")

sentry_sdk.init(dsn=dsn.strip(), debug=True)
```

### Step 3 — Events not appearing in dashboard

**Symptoms:** `Sentry.captureException()` runs without errors, but nothing shows up in the Sentry web UI.

**Root causes and fixes:**

1. **`beforeSend` accidentally returning null:**

```typescript
// WRONG — missing return drops all non-exception events
beforeSend(event) {
  if (event.exception) {
    event.tags = { ...event.tags, has_exception: 'true' };
    return event;
  }
  // Implicit return undefined = event DROPPED
}

// CORRECT — always return event unless you explicitly want to filter
beforeSend(event) {
  if (event.message?.includes('ResizeObserver loop')) {
    return null; // Intentionally drop
  }
  if (event.exception) {
    event.tags = { ...event.tags, has_exception: 'true' };
  }
  return event; // ALWAYS return at the end
}
```

1. **`sampleRate` set to 0:**

```typescript
// WRONG
Sentry.init({ sampleRate: 0, tracesSampleRate: 0 }); // Nothing is sent

// CORRECT
Sentry.init({ sampleRate: 1.0, tracesSampleRate: 0.1 });
```

1. **Missing `await Sentry.flush()` in serverless / CLI contexts:**

```typescript
// WRONG — Lambda/CLI process exits before SDK sends the event
export const handler = async (event) => {
  try {
    return await processRequest(event);
  } catch (error) {
    Sentry.captureException(error);
    throw error; // Process exits, event never sent!
  }
};

// CORRECT — flush before returning
export const handler = async (event) => {
  try {
    return await processRequest(event);
  } catch (error) {
    Sentry.captureException(error);
    await Sentry.flush(2000); // Wait up to 2s for event to send
    throw error;
  }
};
```

**Python (AWS Lambda):**

```python
def handler(event, context):
    try:
        return process_request(event)
    except Exception as e:
        sentry_sdk.capture_exception(e)
        sentry_sdk.flush(timeout=2)  # CRITICAL for Lambda
        raise
```

1. **SDK initialized after error occurs:**

```typescript
// WRONG — error happens before Sentry.init()
import express from 'express';
app.get('/', () => { throw new Error('boom'); }); // Sentry not ready

import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...' }); // Too late

// CORRECT — Sentry FIRST
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...' });
import express from 'express';
```

**Diagnostic checklist for missing events:**

```bash
# 1. Verify DSN is present
echo "DSN set: ${SENTRY_DSN:+yes}"

# 2. Enable debug mode and send test event
node -e "
const Sentry = require('@sentry/node');
Sentry.init({ dsn: process.env.SENTRY_DSN, debug: true });
const id = Sentry.captureMessage('Test from CLI', 'info');
console.log('Event ID:', id);
Sentry.flush(5000).then(() => console.log('Flush complete'));
"

# 3. Check Sentry service status
curl -s https://status.sentry.io/api/v2/status.json | python3 -c "
import sys, json; d = json.load(sys.stdin)
print(f\"Status: {d['status']['description']}\")
" 2>/dev/null || echo "Could not reach status.sentry.io"
```

### Step 4 — Source maps not resolving

**Symptoms:** Stack traces in Sentry show minified variable names and wrong line numbers.

**Root cause 1 — Release version mismatch:** The `release` in `Sentry.init()` must exactly match the release name used during `sentry-cli` upload.

```typescript
Sentry.init({ dsn: process.env.SENTRY_DSN, release: '[email protected]' });
```

```bash
# During build/deploy — same version string
export VERSION="[email protected]"
sentry-cli releases new "$VERSION"
sentry-cli releases files "$VERSION" upload-sourcemaps ./dist \
  --url-prefix '~/static/js'   # Must match how browser loads the files
sentry-cli releases finalize "$VERSION"
```

**Root cause 2 — URL prefix mismatch:**

```bash
# Diagnose with the explain command
sentry-cli sourcemaps explain --org "$SENTRY_ORG" --project "$SENTRY_PROJECT" EVENT_ID
# List uploaded artifacts to verify
sentry-cli releases files "$VERSION" list
```

**Root cause 3 — Source maps uploaded after error occurred:** Sentry does not retroactively apply source maps. Upload before the release goes live.

**Root cause 4 — Build tool not generating source maps:**

```javascript
// webpack: devtool: 'source-map'
// vite: build: { sourcemap: true }
```

### Step 5 — 429 rate limit errors

**Symptoms:** Sentry returns HTTP 429. Events are dropped.

```typescript
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  sampleRate: 0.25,              // Send 25% of errors
  tracesSampleRate: 0.01,        // 1% of transactions
  maxBreadcrumbs: 20,            // Reduce from default 100
  ignoreErrors: [
    'ResizeObserver loop limit exceeded',
    'Non-Error promise rejection captured',
    /Loading chunk \d+ failed/,
    /Failed to fetch/,
  ],
  beforeSend(event) {
    const frames = event.exception?.values?.[0]?.stacktrace?.frames || [];
    if (frames.some(f => f.filename?.includes('extension://'))) return null;
    return event;
  },
});
```

**Check quota:** Settings > Projects > [Project] > Client Keys > Configure > Rate Limiting.

### Step 6 — SDK version conflicts

**Symptoms:** `TypeError: Sentry.X is not a function`, duplicate events, or missing integrations.

```bash
# All @sentry/* packages must share the same major version
npm list | grep @sentry 2>/dev/null
# Fix: npm install @sentry/node@latest @sentry/browser@latest
```

**SDK v8 breaking change:** `@sentry/tracing` is removed. Tracing is built into the core:

```typescript
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: '...', tracesSampleRate: 0.1 }); // No @sentry/tracing needed
```

### Step 7 — Wrong environment tag

```typescript
// WRONG — hardcoded, same value in dev and prod
Sentry.init({ environment: 'production' });

// CORRECT — derive from runtime
Sentry.init({ dsn: process.env.SENTRY_DSN, environment: process.env.NODE_ENV || 'developme