Advanced Sentry troubleshooting for complex SDK issues, silent event drops,
source map failures, distributed tracing gaps, and SDK conflicts.
Use when events silently disappear, source maps fail to resolve,
traces break across service boundaries, or the SDK conflicts with
other libraries like OpenTelemetry or winston.
Trigger with phrases like "sentry events missing", "sentry source maps broken",
"sentry debug", "sentry not capturing errors", "sentry tracing gaps",
"sentry memory leak", "sentry sdk conflict".
Instrucciones de origen · Vista previa de solo lectura
name
sentry-advanced-troubleshooting
description
Advanced Sentry troubleshooting for complex SDK issues, silent event drops,
source map failures, distributed tracing gaps, and SDK conflicts.
Use when events silently disappear, source maps fail to resolve,
traces break across service boundaries, or the SDK conflicts with
other libraries like OpenTelemetry or winston.
Trigger with phrases like "sentry events missing", "sentry source maps broken",
"sentry debug", "sentry not capturing errors", "sentry tracing gaps",
"sentry memory leak", "sentry sdk conflict".
Designed for Claude Code, also compatible with Codex and OpenClaw
Sentry Advanced Troubleshooting
Overview
This skill addresses complex Sentry issues that go beyond basic setup: events that silently drop, source maps that refuse to resolve, distributed traces with gaps between services, SDK memory leaks, conflicts with other observability libraries, and network-level DSN blocking. Each section provides a systematic diagnosis path with concrete commands and code to identify root causes.
Prerequisites
Sentry SDK v8 installed and initialized (see sentry-install-auth skill)
Access to application logs, Sentry dashboard, and project settings
Source maps break when the artifact URL stored in Sentry does not match the URL in the error's stack frame. Use sentry-cli sourcemaps explain to pinpoint the exact mismatch:
# List artifacts uploaded for the current release
RELEASE="${SENTRY_RELEASE:-$(node -e "console.log(require('./package.json').version)")}"echo"Checking release: $RELEASE"
sentry-cli releases files "$RELEASE" list
# Explain why a specific event has unresolved source maps# Get the event ID from the Sentry issue detail page
sentry-cli sourcemaps explain \
--org "$SENTRY_ORG" \
--project "$SENTRY_PROJECT" \
"EVENT_ID_HERE"# Common output: "artifact ~/static/js/main.abc123.js not found"# This means your url-prefix does not match the deployed URL path
Validate before uploading:
# Dry-run upload to catch issues before they affect production
sentry-cli sourcemaps upload \
--release="$RELEASE" \
--url-prefix="~/static/js" \
--validate \
--dry-run \
./dist
# If using a bundler plugin, verify it sets the correct prefix:# Webpack: devtool: 'source-map' (not 'eval-source-map')# Vite: build.sourcemap: true
Check the URL matching rule: The stack frame URL (e.g., https://example.com/static/js/main.abc123.js) must match the artifact URL (e.g., ~/static/js/main.abc123.js) after the tilde prefix substitution. If your CDN rewrites paths, the prefix must account for the rewritten path.
Distributed tracing gaps:
When traces break between services (a parent service starts a trace but the downstream service creates a new unlinked trace), the issue is missing propagation headers:
// Verify propagation headers are being sent// In your HTTP client (axios, fetch, etc.), log outbound headers:import * asSentryfrom'@sentry/node';
// Check: does the active span exist when the outbound call happens?const activeSpan = Sentry.getActiveSpan();
if (!activeSpan) {
console.error('No active span at the point of outbound HTTP call');
console.error('The call must happen INSIDE a Sentry.startSpan() callback');
}
// Manually propagate if auto-instrumentation is not workingconstheaders: Record<string, string> = {};
Sentry.getClient()?.getOptions().tracePropagationTargets; // check targetsconsole.log('tracePropagationTargets:',
Sentry.getClient()?.getOptions().tracePropagationTargets ?? 'default (all)');
// Verify: the downstream service must extract these headers// sentry-trace: <traceId>-<spanId>-<sampled>// baggage: sentry-environment=production,sentry-release=1.0.0,...
// Fix: ensure tracePropagationTargets includes the downstream URLSentry.init({
dsn: process.env.SENTRY_DSN,
tracesSampleRate: 1.0,
// Only propagate to your own services — never to third-party APIstracePropagationTargets: [
'localhost',
/^https:\/\/api\.yourapp\.com/,
/^https:\/\/internal\./,
],
});
Memory leak from unbounded breadcrumbs:
The SDK stores breadcrumbs in memory. In long-running processes (workers, daemons), unbounded accumulation causes heap growth:
// Diagnosis: check breadcrumb count over timesetInterval(() => {
const scope = Sentry.getCurrentScope();
// @ts-expect-error — accessing internal for diagnosis onlyconst breadcrumbs = scope._breadcrumbs?.length ?? 'unknown';
const mem = process.memoryUsage();
console.log('[Sentry Health]', {
breadcrumbs,
heapUsed: `${(mem.heapUsed / 1024 / 1024).toFixed(1)} MB`,
rss: `${(mem.rss / 1024 / 1024).toFixed(1)} MB`,
});
}, 60_000);
// Fix: cap breadcrumbs and disable noisy auto-breadcrumbsSentry.init({
dsn: process.env.SENTRY_DSN,
maxBreadcrumbs: 20, // Default is 100 — reduce for long-running processesintegrations: [
// Disable console breadcrumbs if they flood the bufferSentry.consoleIntegration({ levels: ['error', 'warn'] }),
],
});
Step 3 — Resolve SDK Conflicts, Network Blocks, and Custom Transport Issues
See SDK conflicts, network blocks, and custom transport for OpenTelemetry dual-registration fixes, winston/pino conflict resolution, network proxy/firewall diagnosis (DNS, curl, raw envelope test), custom transport debugging wrappers, and a comprehensive diagnostic shell script.
Output
Root cause identified for silently dropped events (beforeSend, sampling, transport, tunnel)
Source map resolution verified or mismatch pinpointed with sourcemaps explain
Distributed tracing continuity confirmed across service boundaries
Memory leak from breadcrumb accumulation diagnosed and capped
SDK conflicts with OpenTelemetry or logging libraries resolved
Network connectivity to Sentry ingest endpoint verified or proxy identified
Custom transport instrumented with timing and error logging
Error Handling
Symptom
Root Cause
Solution
debug: true prints nothing
SDK never initialized
Verify instrument.mjs loads via --import flag before app code
flush() always times out
Network blocking outbound HTTPS
Check firewall rules, proxy env vars; test with curl to ingest endpoint
Source maps show wrong file
URL prefix does not match stack frame URL
Run sentry-cli sourcemaps explain EVENT_ID to see exact mismatch
Duplicate events in dashboard
Multiple Sentry.init() calls in codebase
Search for all init calls (grep -r "Sentry.init"), consolidate to one file
Heap grows steadily over hours
Unbounded breadcrumb accumulation
Set maxBreadcrumbs: 20, filter noisy console integrations
Traces split into separate transactions
Missing propagation headers to downstream
Verify tracePropagationTargets includes the downstream service URL
Sentry.getActiveSpan() returns undefined
HTTP call is outside a span context
Wrap the call in Sentry.startSpan() or check async context propagation
OpenTelemetry double-tracing
Both Sentry and OTel register global tracer
Use skipOpenTelemetrySetup: true and add SentrySpanProcessor to your OTel SDK
Examples
TypeScript — Full diagnostic init for a production Node.js service:
