fix(core): Prevent recursion when a callback triggers another capture (#5737)

* fix(core): Prevent recursion when a callback triggers another capture

A user beforeSend/beforeBreadcrumb/beforeSendLog callback that itself
captures — directly, or transitively through a logging integration that
routes back into Sentry (e.g. Timber, or the Gradle plugin's logcat
instrumentation) — recursed until a StackOverflowError, because the callbacks
run synchronously on the caller thread with no re-entrancy protection.

Add a shared, thread-local SentryCallbackReentrancyGuard that is set only
while a callback's execute() runs. Capture entry points (captureEvent,
captureTransaction, captureLog, Scope.addBreadcrumb) drop nested captures
while the guard is active, breaking the loop for every capture type at once.
Dropping (rather than sending) the nested capture is intentional: bypassing
beforeSend would send unscrubbed data.

The nested capture is dropped, not sent. This also makes the per-integration
guard in SentryLogcatAdapter redundant.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(changelog): Add entry for callback re-entrancy guard

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(core): Guard captureFeedback, captureReplayEvent, captureMetric too

These three capture methods had their beforeSend* executors wrapped by the
re-entrancy guard but no entry check, so they were never dropped when a
callback was active. That broke the "callbacks never nest" invariant: a
callback that captured feedback/replay/metric ran that executor, whose exit()
cleared the shared flag mid-callback, re-enabling recursion for any
captureEvent/captureLog that followed in the same callback. They also recursed
directly (e.g. beforeSendFeedback -> captureFeedback).

Add the same isActive() entry guard to all three so every executor-wrapped
capture path also drops while a callback runs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(core): Harden re-entrancy guard with depth counter, wrap remaining callbacks

Two robustness fixes for the callback re-entrancy guard:

Replace the boolean flag with a depth counter so a nested exit() cannot
disarm the guard while an outer callback is still running. The boolean
relied on the "callbacks never nest" invariant, which every capture entry
point must uphold by convention - a future capture path added without an
entry check would silently re-open the recursion hole. The counter makes
that failure mode structurally impossible, and lets exit() remove() the
thread-local entry instead of parking a stale value on pooled threads.

Wrap beforeErrorSampling and beforeEnvelopeCallback, the two remaining
user callbacks in SentryClient without enter()/exit(). A capture from
within beforeErrorSampling recursed unguarded (captureEvent ->
beforeErrorSampling -> captureEvent -> ...). Both regression tests were
verified to fail with StackOverflowError without the wraps.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(core): Hand out AutoCloseable token from re-entrancy guard

Replace the manual enter()/finally-exit() pattern at every callback site
with an ISentryLifecycleToken returned from enter(), used via
try-with-resources. This removes nine copies of the finally boilerplate
and the risk of forgetting the exit() call.

The depth counter stays as the guard's state model - the token's close()
just decrements it - so the nesting correctness guarantee is unchanged.
The token is a shared static singleton, so no allocation happens per
callback, matching the AutoClosableReentrantLock idiom already in the
codebase.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Format code

* docs(changelog): Move re-entrancy entry to Unreleased

The rebase folded the previous Unreleased section into the released
8.48.0, stranding the callback re-entrancy entry there. Move it back
under Unreleased.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(core): Guard sendEnvelope against callback re-entrancy

captureEnvelope and captureCheckIn route into sendEnvelope without the
isActive() entry check every other capture path has. A beforeEnvelope
callback that itself captured an envelope or check-in re-entered
sendEnvelope, re-ran the callback, and recursed to a StackOverflowError -
the same failure class the rest of this PR fixes.

Check the guard at the top of sendEnvelope, the single choke point every
send flows through, rather than adding a check to each public entry
point. In normal flow the guard is already inactive there (the before*
callback has exited), so an active guard can only mean a callback
triggered the send, which is dropped. This also closes the hole for any
future sender routed through sendEnvelope.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* test(core): Drop redundant check-in re-entrancy test

captureCheckIn and captureEnvelope both funnel into sendEnvelope and hit
the same isActive() guard, so the check-in test exercised no code path
the envelope test did not already cover.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(core): Drop callback-recursion captures silently

The re-entrancy guard dropped nested captures but logged a DEBUG line at
seven of the eight drop sites. That log is itself routed back into Sentry
by the same logging integrations this guard protects against (the Gradle
plugin's logcat instrumentation feeds captureLog, whose own drop logs
again), so logging on the drop path re-opens the very recursion the guard
breaks. It only bites with SDK debug logging enabled, since the internal
logger is otherwise a no-op, but dropping silently removes the failure
mode outright.

Drop without logging everywhere and document why in the guard's Javadoc
and at each drop site.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(core): Document that captures inside before* callbacks are dropped

A customer implementing beforeSend/beforeBreadcrumb/beforeSendLog/etc.
has no way to know that capturing from within the callback — directly or
through a logging integration — is silently dropped to prevent recursion.
State the contract on each customer-facing callback interface.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* build(core): Update API dump for re-entrancy guard token

The token refactor changed SentryCallbackReentrancyGuard.enter() to
return an ISentryLifecycleToken and made exit() private, but the API dump
was not regenerated at the time. The guard is @ApiStatus.Internal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Sentry Github Bot <bot+github-bot@sentry.io>

Author: 3 people

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 - Backfill release, environment, distribution, tags, and app version/build—and use the matching replay-on-error sample rate—for `ApplicationExitInfo` ANR and native crash events captured before SDK initialization, without reusing options cached by a later app update ([#5762](https://github.com/getsentry/sentry-java/pull/5762))
 - `SentryTagModifierNode.isImportantForBounds` now matches the default behavior and returns `true` ([#5789](https://github.com/getsentry/sentry-java/pull/5789))
+- Prevent a `StackOverflowError` when a `beforeSend`, `beforeBreadcrumb`, `beforeSendLog`, or `beforeEnvelope` callback triggers another capture (directly or through a logging integration such as Timber) ([#5737](https://github.com/getsentry/sentry-java/pull/5737))
+  - Captures made from within a user callback (event, transaction, breadcrumb, log, envelope, or check-in) are now dropped while that callback runs, instead of recursing. Captures made by event processors are unaffected.
 
 ## 8.49.0
 

sentry-android-timber/src/test/java/io/sentry/android/timber/SentryTimberIntegrationTest.kt

@@ -1,17 +1,22 @@
 package io.sentry.android.timber
 
 import io.sentry.IScopes
+import io.sentry.ITransportFactory
+import io.sentry.ScopesAdapter
+import io.sentry.Sentry
 import io.sentry.SentryLevel
 import io.sentry.SentryLogLevel
 import io.sentry.SentryOptions
 import io.sentry.protocol.SdkVersion
+import io.sentry.transport.ITransport
 import kotlin.test.BeforeTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertTrue
 import org.mockito.kotlin.any
 import org.mockito.kotlin.mock
 import org.mockito.kotlin.verify
+import org.mockito.kotlin.whenever
 import timber.log.Timber
 
 class SentryTimberIntegrationTest {
@@ -112,4 +117,43 @@ class SentryTimberIntegrationTest {
 
     assertTrue(fixture.options.sdkVersion!!.integrationSet.contains("Timber"))
   }
+
+  @Test
+  fun `a beforeSend callback that logs via Timber does not recurse`() {
+    // End-to-end guard against SDK-CRASHES-JAVA-3T3H style recursion: with a real Sentry instance,
+    // a beforeSend callback that logs through the planted SentryTimberTree must not loop back into
+    // capture forever.
+    val transport = mock<ITransport>()
+    val transportFactory = mock<ITransportFactory>()
+    whenever(transportFactory.create(any(), any())).thenReturn(transport)
+
+    var beforeSendInvocations = 0
+    Sentry.init { options ->
+      options.dsn = "https://key@sentry.io/123"
+      options.setTransportFactory(transportFactory)
+      options.beforeSend = SentryOptions.BeforeSendCallback { event, _ ->
+        beforeSendInvocations++
+        Timber.e("logging from beforeSend")
+        event
+      }
+    }
+    Timber.plant(
+      SentryTimberTree(
+        ScopesAdapter.getInstance(),
+        SentryLevel.ERROR,
+        SentryLevel.INFO,
+        SentryLogLevel.INFO,
+      )
+    )
+
+    try {
+      Timber.e("outer error")
+
+      // Without the core re-entrancy guard this recurses until a StackOverflowError. The nested
+      // Timber.e is dropped before its own beforeSend, so the callback runs exactly once.
+      assertEquals(1, beforeSendInvocations)
+    } finally {
+      Sentry.close()
+    }
+  }
 }

sentry/api/sentry.api

@@ -7924,6 +7924,11 @@ public final class io/sentry/util/ScopesUtil {
 	public static fun printScopesChain (Lio/sentry/IScopes;)V
 }
 
+public final class io/sentry/util/SentryCallbackReentrancyGuard {
+	public static fun enter ()Lio/sentry/ISentryLifecycleToken;
+	public static fun isActive ()Z
+}
+
 public final class io/sentry/util/SentryRandom {
 	public fun <init> ()V
 	public static fun current ()Lio/sentry/util/Random;

sentry/src/main/java/io/sentry/Scope.java

@@ -16,6 +16,7 @@
 import io.sentry.util.ExceptionUtils;
 import io.sentry.util.Objects;
 import io.sentry.util.Pair;
+import io.sentry.util.SentryCallbackReentrancyGuard;
 import java.lang.ref.WeakReference;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -464,7 +465,7 @@ public Queue<Breadcrumb> getBreadcrumbs() {
       final @NotNull SentryOptions.BeforeBreadcrumbCallback callback,
       @NotNull Breadcrumb breadcrumb,
       final @NotNull Hint hint) {
-    try {
+    try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
       breadcrumb = callback.execute(breadcrumb, hint);
     } catch (Throwable e) {
       options
@@ -493,6 +494,10 @@ public void addBreadcrumb(@NotNull Breadcrumb breadcrumb, @Nullable Hint hint) {
     if (breadcrumb == null || breadcrumbs instanceof DisabledQueue) {
       return;
     }
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return;
+    }
     SentryOptions.BeforeBreadcrumbCallback callback = options.getBeforeBreadcrumb();
     if (callback != null) {
       if (hint == null) {

sentry/src/main/java/io/sentry/SentryClient.java

@@ -107,6 +107,11 @@ private boolean shouldApplyScopeData(final @NotNull CheckIn event, final @NotNul
       @NotNull SentryEvent event, final @Nullable IScope scope, @Nullable Hint hint) {
     Objects.requireNonNull(event, "SentryEvent is required.");
 
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return SentryId.EMPTY_ID;
+    }
+
     if (hint == null) {
       hint = new Hint();
     }
@@ -236,7 +241,7 @@ private boolean shouldApplyScopeData(final @NotNull CheckIn event, final @NotNul
       final SentryReplayOptions.BeforeErrorSamplingCallback beforeErrorSampling =
           options.getSessionReplay().getBeforeErrorSampling();
       if (beforeErrorSampling != null) {
-        try {
+        try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
           shouldCaptureReplay = beforeErrorSampling.execute(event, hint);
         } catch (Throwable e) {
           options
@@ -312,6 +317,11 @@ private void finalizeTransaction(final @NotNull IScope scope, final @NotNull Hin
       @NotNull SentryReplayEvent event, final @Nullable IScope scope, @Nullable Hint hint) {
     Objects.requireNonNull(event, "SessionReplay is required.");
 
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return SentryId.EMPTY_ID;
+    }
+
     if (hint == null) {
       hint = new Hint();
     }
@@ -937,10 +947,19 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
 
   private @NotNull SentryId sendEnvelope(
       @NotNull final SentryEnvelope envelope, @Nullable final Hint hint) throws IOException {
+    // captureEnvelope and captureCheckIn have no entry-level guard, so a callback that captures
+    // one of those would recurse back into beforeEnvelopeCallback. In normal flow the guard is
+    // already inactive by the time we get here (the before* callback has exited), so an active
+    // guard means a callback triggered this send. Drop silently: a log here can re-enter through a
+    // logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return SentryId.EMPTY_ID;
+    }
+
     final @Nullable SentryOptions.BeforeEnvelopeCallback beforeEnvelopeCallback =
         options.getBeforeEnvelopeCallback();
     if (beforeEnvelopeCallback != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         beforeEnvelopeCallback.execute(envelope, hint);
       } catch (Throwable e) {
         options
@@ -969,6 +988,11 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
       final @Nullable ProfilingTraceData profilingTraceData) {
     Objects.requireNonNull(transaction, "Transaction is required.");
 
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return SentryId.EMPTY_ID;
+    }
+
     if (hint == null) {
       hint = new Hint();
     }
@@ -1187,6 +1211,11 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
   @Override
   public @NotNull SentryId captureFeedback(
       final @NotNull Feedback feedback, @Nullable Hint hint, final @NotNull IScope scope) {
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return SentryId.EMPTY_ID;
+    }
+
     SentryEvent event = new SentryEvent();
     event.getContexts().setFeedback(feedback);
 
@@ -1297,6 +1326,11 @@ public void captureSession(final @NotNull Session session, final @Nullable Hint
   @ApiStatus.Experimental
   @Override
   public void captureLog(@Nullable SentryLogEvent logEvent, @Nullable IScope scope) {
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return;
+    }
+
     if (logEvent != null && scope != null) {
       logEvent = processLogEvent(logEvent, scope.getEventProcessors());
       if (logEvent == null) {
@@ -1351,6 +1385,11 @@ public void captureMetric(
       @Nullable SentryMetricsEvent metricsEvent,
       final @Nullable IScope scope,
       @Nullable Hint hint) {
+    // Drop silently to prevent recursion; a log here can re-enter through a logging integration.
+    if (SentryCallbackReentrancyGuard.isActive()) {
+      return;
+    }
+
     if (hint == null) {
       hint = new Hint();
     }
@@ -1612,7 +1651,7 @@ private void sortBreadcrumbsByDate(
       @NotNull SentryEvent event, final @NotNull Hint hint) {
     final SentryOptions.BeforeSendCallback beforeSend = options.getBeforeSend();
     if (beforeSend != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSend.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1634,7 +1673,7 @@ private void sortBreadcrumbsByDate(
     final SentryOptions.BeforeSendTransactionCallback beforeSendTransaction =
         options.getBeforeSendTransaction();
     if (beforeSendTransaction != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         transaction = beforeSendTransaction.execute(transaction, hint);
       } catch (Throwable e) {
         options
@@ -1655,7 +1694,7 @@ private void sortBreadcrumbsByDate(
       @NotNull SentryEvent event, final @NotNull Hint hint) {
     final SentryOptions.BeforeSendCallback beforeSendFeedback = options.getBeforeSendFeedback();
     if (beforeSendFeedback != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendFeedback.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1673,7 +1712,7 @@ private void sortBreadcrumbsByDate(
       @NotNull SentryReplayEvent event, final @NotNull Hint hint) {
     final SentryOptions.BeforeSendReplayCallback beforeSendReplay = options.getBeforeSendReplay();
     if (beforeSendReplay != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendReplay.execute(event, hint);
       } catch (Throwable e) {
         options
@@ -1694,7 +1733,7 @@ private void sortBreadcrumbsByDate(
     final SentryOptions.Logs.BeforeSendLogCallback beforeSendLog =
         options.getLogs().getBeforeSend();
     if (beforeSendLog != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendLog.execute(event);
       } catch (Throwable e) {
         options
@@ -1716,7 +1755,7 @@ private void sortBreadcrumbsByDate(
     final SentryOptions.Metrics.BeforeSendMetricCallback beforeSendMetric =
         options.getMetrics().getBeforeSend();
     if (beforeSendMetric != null) {
-      try {
+      try (final @NotNull ISentryLifecycleToken ignored = SentryCallbackReentrancyGuard.enter()) {
         event = beforeSendMetric.execute(event, hint);
       } catch (Throwable e) {
         options

sentry/src/main/java/io/sentry/SentryOptions.java

@@ -3327,6 +3327,10 @@ public interface BeforeSendCallback {
     /**
      * Mutates or drop an event before being sent
      *
+     * <p>Do not capture from within this callback — directly, or indirectly through a logging
+     * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+     * prevent infinite recursion.
+     *
      * @param event the event
      * @param hint the hints
      * @return the original event or the mutated event or null if event was dropped
@@ -3341,6 +3345,10 @@ public interface BeforeSendTransactionCallback {
     /**
      * Mutates or drop a transaction before being sent
      *
+     * <p>Do not capture from within this callback — directly, or indirectly through a logging
+     * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+     * prevent infinite recursion.
+     *
      * @param transaction the transaction
      * @param hint the hints
      * @return the original transaction or the mutated transaction or null if transaction was
@@ -3358,6 +3366,10 @@ public interface BeforeSendReplayCallback {
      * for a single replay (i.e. segments), you can check {@link SentryReplayEvent#getReplayId()} to
      * identify that the segments belong to the same replay.
      *
+     * <p>Do not capture from within this callback — directly, or indirectly through a logging
+     * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+     * prevent infinite recursion.
+     *
      * @param event the event
      * @param hint the hint, contains {@link ReplayRecording}, can be accessed via {@link
      *     Hint#getReplayRecording()}
@@ -3373,6 +3385,10 @@ public interface BeforeBreadcrumbCallback {
     /**
      * Mutates or drop a callback before being added
      *
+     * <p>Do not capture from within this callback — directly, or indirectly through a logging
+     * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+     * prevent infinite recursion.
+     *
      * @param breadcrumb the breadcrumb
      * @param hint the hints, usually the source of the breadcrumb
      * @return the original breadcrumb or the mutated breadcrumb of null if breadcrumb was dropped
@@ -3961,6 +3977,10 @@ public interface BeforeSendLogCallback {
       /**
        * Mutates or drop a log event before being sent
        *
+       * <p>Do not capture from within this callback — directly, or indirectly through a logging
+       * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+       * prevent infinite recursion.
+       *
        * @param event the event
        * @return the original log event or the mutated event or null if event was dropped
        */
@@ -4035,6 +4055,10 @@ public interface BeforeSendMetricCallback {
       /**
        * A callback which gets called right before a metric is about to be sent.
        *
+       * <p>Do not capture from within this callback — directly, or indirectly through a logging
+       * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+       * prevent infinite recursion.
+       *
        * @param metric the metric
        * @return the original metric, mutated metric or null if metric was dropped
        */

sentry/src/main/java/io/sentry/SentryReplayOptions.java

@@ -28,6 +28,10 @@ public interface BeforeErrorSamplingCallback {
     /**
      * Determines whether replay capture should proceed for the given error event.
      *
+     * <p>Do not capture from within this callback — directly, or indirectly through a logging
+     * integration that routes logs back into Sentry. Such nested captures are silently dropped to
+     * prevent infinite recursion.
+     *
      * @param event the error event that triggered the replay capture
      * @param hint the hint associated with the event
      * @return {@code true} if the error sample rate should be checked, {@code false} to skip replay