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:

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

// 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:

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()

Root causes and fixes:

1. beforeSend

   accidentally returning null:

// 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
}

2. sampleRate

   set to 0:

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

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

3. Missing

   await Sentry.flush()

   in serverless / CLI contexts:

// 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):

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

4. SDK initialized after error occurs:

// 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:

# 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

Sentry.init()

sentry-cli

Sentry.init({ dsn: process.env.SENTRY_DSN, release: 'my-app@1.2.3' });

# During build/deploy — same version string
export VERSION="my-app@1.2.3"
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:

# 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:

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

Step 5 — 429 rate limit errors

Symptoms: Sentry returns HTTP 429. Events are dropped.

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

# 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

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

Step 7 — Wrong environment tag

// 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 || 'development' });

Step 8 — CORS issues with browser SDK

The standard SDK sends to

https://<org>.ingest.sentry.io

1. CSP blocking — add

   connect-src 'self' https://*.ingest.sentry.io

   to your CSP
2. Tunnel misconfiguration — your tunnel endpoint must proxy and return CORS headers
3. Ad blockers — use the

   tunnel

   option to route through your domain

Sentry.init({ dsn: process.env.SENTRY_DSN, tunnel: '/api/sentry-tunnel' });

Step 9 — Node.js process exits before events are sent

The SDK batches events asynchronously. Short-lived processes must flush before exit.

async function main() {
  try { await doWork(); }
  catch (error) { Sentry.captureException(error); }
  finally { await Sentry.flush(5000); } // CRITICAL
}

// Graceful shutdown for servers
process.on('SIGTERM', async () => {
  await Sentry.flush(5000);
  server.close(() => process.exit(0));
});

Step 10 — Express "not instrumented" warning

Sentry must initialize before importing Express so it can monkey-patch HTTP modules:

// instrument.mjs — imported first
import * as Sentry from '@sentry/node';
Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 });

// app.mjs
import './instrument.mjs'; // FIRST
import express from 'express';
const app = express();
Sentry.setupExpressErrorHandler(app); // After all routes

Or use

node --import ./instrument.mjs app.mjs

Output

• Root cause identified from the diagnostic steps above
• Configuration fix applied and verified with a test event

• debug: true

  output confirming SDK initialization and event delivery
• Test event visible in Sentry dashboard (search by Event ID)

• debug: true

  removed after issue is resolved

Error Handling

Invalid Sentry Dsn

https://<key>@<org>.ingest.sentry.io/<id>

beforeSend

undefined

return event

beforeSend

return null

sampleRate

0

sampleRate: 1.0

tracesSampleRate

await Sentry.flush(2000)

process.exit()

Sentry.init({ release })

release

Sentry.init()

sentry-cli releases

--url-prefix

sentry-cli sourcemaps explain EVENT_ID

429 Too Many Requests

sampleRate

tracesSampleRate

ignoreErrors

TypeError: Sentry.X is not a function

npm list @sentry/core

@sentry/*

Sentry.init()

import express

instrument.mjs

node --import

environment

environment: process.env.NODE_ENV

Sentry.init()

*.ingest.sentry.io

connect-src https://*.ingest.sentry.io

Sentry.captureException('string')

new Error('message')

ERR_REQUIRE_ESM

--import

Examples

Example 1: Debug missing events in a Next.js app Request: "Sentry captureException runs but nothing shows in the dashboard" Steps: Enable

debug: true

Sentry.init()

NEXT_PUBLIC_SENTRY_DSN

.env.production

Example 2: Fix source maps in a Vite + React app Request: "Stack traces in Sentry are all minified" Steps: Ran

sentry-cli sourcemaps explain EVENT_ID

--url-prefix

~/dist

~/assets

--url-prefix '~/assets'

Example 3: Lambda events disappearing Request: "Sentry.captureException works locally but not in AWS Lambda" Steps: Added

await Sentry.flush(2000)

Sentry.wrapHandler()

Resources

• JavaScript Troubleshooting Guide
• Source Maps Troubleshooting
• Python Troubleshooting
• Filtering & Sampling Events
• sentry-cli Source Maps Upload
• Sentry Service Status
• SDK Migration Guide v7 to v8

Next Steps

• After fixing, send a test event with

  Sentry.captureMessage('verify-fix', 'info')

  and confirm it appears
• Disable

  debug: true

  before deploying to production
• Consider setting up Sentry alerts to catch future issues early
• Review the

  sentry-rate-limits

  skill if you hit 429 errors frequently
• Review the

  sentry-release-management

  skill for source map upload automation