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."
// WRONG — DSN is undefined because env var is missing or misspelledSentry.init({
dsn: process.env.SENTRI_DSN, // Typo in env var name
});
// CORRECT — validate DSN is present before initconst dsn = process..;
(!dsn) {
.();
process.();
}
.({
: dsn.(),
: ,
});
# During build/deploy — same version stringexport 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:
Symptoms:TypeError: Sentry.X is not a function, duplicate events, or missing integrations.
# 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:
// WRONG — hardcoded, same value in dev and prodSentry.init({ environment: 'production' });
// CORRECT — derive from runtimeSentry.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 which has permissive CORS. If you see CORS errors:
CSP blocking — add connect-src 'self' https://*.ingest.sentry.io to your CSP
Tunnel misconfiguration — your tunnel endpoint must proxy and return CORS headers
Ad blockers — use the tunnel option to route through your domain
Add explicit return event as the last line of beforeSend. Use return null only for intentional filtering
No events in dashboard
sampleRate set to 0
Set sampleRate: 1.0 (default) for errors. Use fractional values only for tracesSampleRate
No events in serverless/CLI
Process exits before SDK flushes its queue
Add await Sentry.flush(2000) before process.exit(), Lambda return, or CLI exit
Minified stack traces
Source map release version does not match Sentry.init({ release })
Ensure release string is identical in both Sentry.init() and sentry-cli releases upload
Minified stack traces
--url-prefix does not match browser JS URL path
Run sentry-cli sourcemaps explain EVENT_ID to diagnose the prefix
429 Too Many Requests
Project or org quota exceeded
Lower sampleRate/tracesSampleRate, add ignoreErrors, set server-side rate limits
TypeError: Sentry.X is not a function
Mixed SDK major versions (v7 + v8)
Run npm list @sentry/core to find duplicates. Upgrade all @sentry/* to same major
Express not instrumented
Sentry.init() called after import express
Move init to instrument.mjs and import first, or use node --import
Wrong environment in events
environment hardcoded or not set
Set environment: process.env.NODE_ENV in Sentry.init()
CORS errors in browser
CSP blocking *.ingest.sentry.io or tunnel missing headers
Add connect-src https://*.ingest.sentry.io to CSP, or fix tunnel CORS
Duplicate events
Error captured at multiple layers
Capture at ONE level only — catch block OR error middleware, not both
Missing stack traces
Sentry.captureException('string') instead of Error
Always pass new Error('message') — strings have no stack trace
ESM ERR_REQUIRE_ESM
Node.js version below 18.19 for ESM support
Upgrade to Node.js 18.19+ or 20.6+. Use --import flag
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 in Sentry.init(). Console showed "No DSN provided." The NEXT_PUBLIC_SENTRY_DSN env var was not set in .env.production. Added the variable, redeployed, confirmed events arrive within seconds.
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 which reported "source map not found for URL ~/assets/index-abc123.js". The --url-prefix was ~/dist but Vite serves from ~/assets. Fixed to --url-prefix '~/assets' and re-uploaded. Stack traces now resolve correctly.
Example 3: Lambda events disappearing
Request: "Sentry.captureException works locally but not in AWS Lambda"
Steps: Added await Sentry.flush(2000) before the Lambda handler returns. Events now arrive consistently. Wrapped handler with Sentry.wrapHandler() for automatic scope management.
