@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+### Behavioral Changes
+
+- The outbox and cache directories are no longer created by `Sentry.init` ([#5792](https://github.com/getsentry/sentry-java/pull/5792))
+  - They are now created lazily by whichever component first writes into them, off the init thread. As a result, the directories at `SentryOptions.getOutboxPath()` and `SentryOptions.getCacheDirPath()` are not guaranteed to exist once `Sentry.init` returns.
+  - If you write envelopes into the outbox path yourself instead of going through the SDK — as hybrid SDKs do for `captureEnvelope` — create the directory first, e.g. `new File(outboxPath).mkdirs()`.
+
 ### Improvements
 
 - Skip building Android manifest metadata debug log messages when debug logging is disabled, reducing allocations during SDK init ([#5790](https://github.com/getsentry/sentry-java/pull/5790))
@@ -14,6 +20,7 @@
 
 ### Performance
 
+- Create the outbox and cache directories lazily in their consumers instead of during SDK init, moving the `mkdirs()` calls off the init (main) thread ([#5792](https://github.com/getsentry/sentry-java/pull/5792))
 - Reduce the number of SDK threads: `LifecycleWatcher` now schedules the session-end task on the shared timer executor instead of creating a dedicated `java.util.Timer` thread ([#5819](https://github.com/getsentry/sentry-java/pull/5819))
 - Reduce the number of SDK threads: `RateLimiter` now schedules its rate-limit-lifted notifications on the shared timer executor instead of creating a dedicated `java.util.Timer` thread ([#5814](https://github.com/getsentry/sentry-java/pull/5814))
 - Speed up deserialization of arbitrary JSON objects by typing numbers without throwing exceptions ([#5783](https://github.com/getsentry/sentry-java/pull/5783))
 
@@ -10,8 +10,10 @@
 import io.sentry.SentryLevel;
 import io.sentry.SentryOptions;
 import io.sentry.util.AutoClosableReentrantLock;
+import io.sentry.util.FileUtils;
 import io.sentry.util.Objects;
 import java.io.Closeable;
+import java.io.File;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.TestOnly;
@@ -67,6 +69,12 @@ private void startOutboxSender(
       final @NotNull IScopes scopes,
       final @NotNull SentryOptions options,
       final @NotNull String path) {
+    // Create the outbox dir here (on the executor) so the observer can watch it for envelopes
+    // written by hybrid SDKs, instead of blocking Sentry.init on the mkdirs.
+    if (!FileUtils.createDirectory(new File(path))) {
+      options.getLogger().log(SentryLevel.ERROR, "Failed to create outbox dir %s", path);
+    }
+
     final OutboxSender outboxSender =
         new OutboxSender(
             scopes,
 
@@ -93,7 +93,7 @@ private boolean storeInternalAndroid(@NotNull SentryEnvelope envelope, @NotNull
 
   @TestOnly
   public @NotNull File getDirectory() {
-    return directory;
+    return directory.getFile();
   }
 
   private void writeStartupCrashMarkerFile() {
@@ -106,7 +106,14 @@ private void writeStartupCrashMarkerFile() {
           .log(DEBUG, "Outbox path is null, the startup crash marker file will not be written");
       return;
     }
-    final File crashMarkerFile = new File(outboxPath, STARTUP_CRASH_MARKER_FILE);
+    // The outbox dir is no longer created during Sentry.init, so create it here in case the native
+    // SDK (which normally creates it) is disabled.
+    final File outboxDir = new File(outboxPath);
+    if (!FileUtils.createDirectory(outboxDir)) {
+      options.getLogger().log(ERROR, "Failed to create outbox dir %s", outboxPath);
+      return;
+    }
+    final File crashMarkerFile = new File(outboxDir, STARTUP_CRASH_MARKER_FILE);
     try {
       crashMarkerFile.createNewFile();
     } catch (Throwable e) {
 
@@ -14,6 +14,8 @@ import kotlin.test.AfterTest
 import kotlin.test.BeforeTest
 import kotlin.test.Test
 import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
 import org.junit.runner.RunWith
 import org.mockito.kotlin.eq
 import org.mockito.kotlin.mock
@@ -122,4 +124,19 @@ class EnvelopeFileObserverIntegrationTest {
     verify(fixture.logger)
       .log(eq(SentryLevel.DEBUG), eq("EnvelopeFileObserverIntegration installed."))
   }
+
+  @Test
+  fun `register creates the outbox dir when it does not exist yet`() {
+    val outboxDir = File(file, "outbox")
+    assertFalse(outboxDir.exists())
+
+    fixture.getSut { it.executorService = ImmediateExecutorService() }
+    val integration =
+      object : EnvelopeFileObserverIntegration() {
+        override fun getPath(options: SentryOptions): String = outboxDir.absolutePath
+      }
+    integration.register(fixture.scopes, fixture.scopes.options)
+
+    assertTrue(outboxDir.isDirectory)
+  }
 }
@@ -125,6 +125,20 @@ class AndroidEnvelopeCacheTest {
     assertTrue(fixture.startupCrashMarkerFile.exists())
   }
 
+  @Test
+  fun `creates outbox dir when writing startup crash file and dir does not exist yet`() {
+    val cache = fixture.getSut(dir = tmpDir, appStartMillis = 1000L, currentTimeMillis = 2000L)
+
+    val outboxDir = File(fixture.options.outboxPath!!)
+    assertTrue(outboxDir.deleteRecursively())
+    assertFalse(outboxDir.exists())
+
+    val hints = HintUtils.createWithTypeCheckHint(UncaughtHint())
+    cache.storeEnvelope(fixture.envelope, hints)
+
+    assertTrue(fixture.startupCrashMarkerFile.exists())
+  }
+
   @Test
   fun `when no AnrV2 hint exists, does not write last anr report file`() {
     val cache = fixture.getSut(tmpDir)
 
@@ -66,6 +66,9 @@ class MainActivity : ComponentActivity() {
             Button(onClick = { Sentry.close() }) { Text("Close SDK") }
             Button(
               onClick = {
+                // The SDK creates the outbox dir lazily on its executor, so an external
+                // writer has to create it itself.
+                File(outboxPath).mkdirs()
                 val file = File(outboxPath, "corrupted.envelope")
                 val corruptedEnvelopeContent =
                   """
 
@@ -262,9 +262,14 @@ class EnvelopeTests : BaseUiTest() {
       optionsRef = options
     }
 
+    // The SDK creates the outbox dir lazily on its executor, so an external writer racing
+    // Sentry.init has to create it itself.
+    val outboxDir = File(optionsRef!!.outboxPath!!)
+    outboxDir.mkdirs()
+
     // based on
     // https://github.com/getsentry/sentry-native/blob/20d5d5f75f1f48228f2f47e2bb99b17f9996ebbf/ndk/lib/src/androidTest/java/io/sentry/ndk/SentryNdkTest.java#L131
-    File(optionsRef!!.outboxPath, "14779dbf-b2f0-4c00-f4e5-4a287abc4267")
+    File(outboxDir, "14779dbf-b2f0-4c00-f4e5-4a287abc4267")
       .writeText(
         """
         {"dsn":"https://key@sentry.io/proj","event_id":"729ff878-5539-458d-f657-a1acf423a127","sent_at":"2025-04-02T10:02:04.732577Z"}
 
@@ -7692,6 +7692,7 @@ public final class io/sentry/util/ExceptionUtils {
 
 public final class io/sentry/util/FileUtils {
 	public fun <init> ()V
+	public static fun createDirectory (Ljava/io/File;)Z
 	public static fun deleteRecursively (Ljava/io/File;)Z
 	public static fun readBytesFromFile (Ljava/lang/String;J)[B
 	public static fun readText (Ljava/io/File;)Ljava/lang/String;
@@ -7757,6 +7758,12 @@ public final class io/sentry/util/JsonSerializationUtils {
 	public static fun calendarToMap (Ljava/util/Calendar;)Ljava/util/Map;
 }
 
+public final class io/sentry/util/LazyDirectory {
+	public fun <init> (Ljava/lang/String;)V
+	public fun getFile ()Ljava/io/File;
+	public fun getOrCreate ()Ljava/io/File;
+}
+
 public final class io/sentry/util/LazyEvaluator {
 	public fun <init> (Lio/sentry/util/LazyEvaluator$Evaluator;)V
 	public fun getValue ()Ljava/lang/Object;
 
@@ -463,8 +463,9 @@ private static void handleAppStartProfilingConfig(
           () -> {
             final String cacheDirPath = options.getCacheDirPathWithoutDsn();
             if (cacheDirPath != null) {
+              final @NotNull File cacheDir = new File(cacheDirPath);
               final @NotNull File appStartProfilingConfigFile =
-                  new File(cacheDirPath, APP_START_PROFILING_CONFIG_FILE_NAME);
+                  new File(cacheDir, APP_START_PROFILING_CONFIG_FILE_NAME);
               try {
                 // We always delete the config file for app start profiling
                 FileUtils.deleteRecursively(appStartProfilingConfigFile);
@@ -481,6 +482,14 @@ private static void handleAppStartProfilingConfig(
                           "Tracing is disabled and app start profiling will not start.");
                   return;
                 }
+                // The cache dir is no longer created during init, so create it here before writing:
+                // createNewFile() fails if the parent is missing.
+                if (!FileUtils.createDirectory(cacheDir)) {
+                  options
+                      .getLogger()
+                      .log(SentryLevel.ERROR, "Failed to create cache dir %s", cacheDirPath);
+                  return;
+                }
                 if (appStartProfilingConfigFile.createNewFile()) {
                   // If old app start profiling is false, it means the transaction will not be
                   // sampled, but we create the file anyway to allow continuous profiling on app
@@ -616,19 +625,14 @@ private static void initConfigurations(final @NotNull SentryOptions options) {
     // TODO: read values from conf file, Build conf or system envs
     // eg release, distinctId, sentryClientName
 
-    // this should be after setting serializers
-    final String outboxPath = options.getOutboxPath();
-    if (outboxPath != null) {
-      final File outboxDir = new File(outboxPath);
-      outboxDir.mkdirs();
-    } else {
+    // The outbox and cache dirs are created lazily by their consumers (envelope cache, outbox file
+    // observer, native SDK) off the init thread, so we don't stat/mkdir them here.
+    if (options.getOutboxPath() == null) {
       logger.log(SentryLevel.INFO, "No outbox dir path is defined in options.");
     }
 
     final String cacheDirPath = options.getCacheDirPath();
     if (cacheDirPath != null) {
-      final File cacheDir = new File(cacheDirPath);
-      cacheDir.mkdirs();
       final IEnvelopeCache envelopeCache = options.getEnvelopeDiskCache();
       // only overwrite the cache impl if it's not already set
       if (envelopeCache instanceof NoOpEnvelopeCache) {
 
@@ -1104,7 +1104,11 @@ String getCacheDirPathWithoutDsn() {
   }
 
   /**
-   * Returns the outbox path if cacheDirPath is set
+   * Returns the outbox path if cacheDirPath is set.
+   *
+   * <p>The directory is created lazily by the SDK on a background thread, so it is not guaranteed
+   * to exist when {@code Sentry.init} returns. Callers writing envelopes here directly (for example
+   * hybrid SDKs) must create it themselves, e.g. {@code new File(outboxPath).mkdirs()}.
    *
    * @return the outbox path or null if not set
    */
Original file line number	Diff line number	Diff line change
`@@ -1104,7 +1104,11 @@ String getCacheDirPathWithoutDsn() {`
`1104`	`1104`	`}`
`1105`	`1105`
`1106`	`1106`	`/**`
`1107`		`- * Returns the outbox path if cacheDirPath is set`
	`1107`	`+ * Returns the outbox path if cacheDirPath is set.`
	`1108`	`+ *`
	`1109`	`+ * <p>The directory is created lazily by the SDK on a background thread, so it is not guaranteed`
	`1110`	`+ * to exist when {@code Sentry.init} returns. Callers writing envelopes here directly (for example`
	`1111`	`+ * hybrid SDKs) must create it themselves, e.g. {@code new File(outboxPath).mkdirs()}.`
`1108`	`1112`	`*`
`1109`	`1113`	`* @return the outbox path or null if not set`
`1110`	`1114`	`*/`