docs: introduce and document SystemStorageException

This bug is commonly triggered by an `Android/data` directory corruption
bug on Pixel phones: https://issuetracker.google.com/issues/460912704

But there are other unknown causes

It should be handled on startup

Issue 13207

Author: david-allison

AnkiDroid/src/main/java/com/ichi2/anki/AnkiActivity.kt

@@ -75,6 +75,7 @@ import com.ichi2.anki.dialogs.ExportReadyDialog.Companion.KEY_EXPORT_PATH
 import com.ichi2.anki.dialogs.ExportReadyDialog.Companion.REQUEST_EXPORT_SAVE
 import com.ichi2.anki.dialogs.ExportReadyDialog.Companion.REQUEST_EXPORT_SHARE
 import com.ichi2.anki.dialogs.SimpleMessageDialog
+import com.ichi2.anki.exception.SystemStorageException
 import com.ichi2.anki.libanki.Collection
 import com.ichi2.anki.preferences.sharedPrefs
 import com.ichi2.anki.receiver.SdCardReceiver
@@ -740,6 +741,8 @@ open class AnkiActivity(
      *
      * @return `true`: activity may continue to start, `false`: [onCreate] should stop executing
      * as storage permissions are mot granted
+     *
+     * @throws SystemStorageException if `getExternalFilesDir` returns null
      */
     fun ensureStoragePermissions(): Boolean {
         if (IntentHandler.grantedStoragePermissions(this, showToast = true)) {

AnkiDroid/src/main/java/com/ichi2/anki/CollectionHelper.kt

@@ -28,6 +28,7 @@ import com.ichi2.anki.CollectionHelper.getCurrentAnkiDroidDirectory
 import com.ichi2.anki.CollectionHelper.getDefaultAnkiDroidDirectory
 import com.ichi2.anki.backend.createDatabaseUsingAndroidFramework
 import com.ichi2.anki.exception.StorageAccessException
+import com.ichi2.anki.exception.SystemStorageException
 import com.ichi2.anki.exception.UnknownDatabaseVersionException
 import com.ichi2.anki.libanki.Collection
 import com.ichi2.anki.libanki.CollectionFiles
@@ -175,6 +176,8 @@ object CollectionHelper {
      * very different things as explained above.
      *
      * @return Absolute Path to the default location starting location for the AnkiDroid directory
+     *
+     * @throws SystemStorageException if `getExternalFilesDir` returns null
      */
     // TODO Tracked in https://github.com/ankidroid/Anki-Android/issues/5304
     @CheckResult
@@ -215,6 +218,8 @@ object CollectionHelper {
      *
      * @param context Used to get the External App-Specific directory for AnkiDroid
      * @return Returns the absolute path to the App-Specific External AnkiDroid directory
+     *
+     * @throws SystemStorageException if `getExternalFilesDir` returns null
      */
     private fun getAppSpecificExternalAnkiDroidDirectory(context: Context): String? {
         val externalFilesDir = context.getExternalFilesDir(null)
@@ -224,9 +229,9 @@ object CollectionHelper {
         // we will now check for null and if so try to log more information about why.
         if (externalFilesDir == null) {
             Timber.e("Attempting to determine collection path, but no valid external storage?")
-            throw IllegalStateException(
-                "getExternalFilesDir unexpectedly returned null. Media state: " +
-                    Environment.getExternalStorageState(),
+            throw SystemStorageException.build(
+                errorDetail = "getExternalFilesDir unexpectedly returned null",
+                infoUri = "https://github.com/ankidroid/Anki-Android/issues/13207",
             )
         }
         return externalFilesDir.absolutePath
@@ -262,6 +267,8 @@ object CollectionHelper {
 
     /**
      * @return the absolute path to the AnkiDroid directory.
+     *
+     * @throws SystemStorageException if `getExternalFilesDir` returns null
      */
     fun getCurrentAnkiDroidDirectory(context: Context): File =
         getCurrentAnkiDroidDirectoryOptionalContext(context.sharedPrefs()) { context }

AnkiDroid/src/main/java/com/ichi2/anki/IntentHandler.kt

@@ -32,6 +32,7 @@ import com.ichi2.anki.common.utils.trimToLength
 import com.ichi2.anki.dialogs.DialogHandler.Companion.storeMessage
 import com.ichi2.anki.dialogs.DialogHandlerMessage
 import com.ichi2.anki.dialogs.requireDeckPickerOrShowError
+import com.ichi2.anki.exception.SystemStorageException
 import com.ichi2.anki.libanki.DeckId
 import com.ichi2.anki.noteeditor.NoteEditorLauncher
 import com.ichi2.anki.servicelayer.ScopedStorageService
@@ -350,6 +351,8 @@ class IntentHandler : AbstractIntentHandler() {
         /** Checks whether storage permissions are granted on the device. If the device is not using legacy storage,
          *  it verifies if the app has been granted the necessary storage access permission.
          *  @return `true`: if granted, otherwise `false` and shows a missing permission toast
+         *
+         * @throws SystemStorageException if `getExternalFilesDir` returns null
          */
         fun grantedStoragePermissions(
             context: Context,

AnkiDroid/src/main/java/com/ichi2/anki/exception/StorageAccessException.kt

@@ -16,6 +16,11 @@
 
 package com.ichi2.anki.exception
 
+/**
+ * If a known storage path is unusable
+ *
+ * @see [SystemStorageException] if no path is available
+ */
 class StorageAccessException(
     msg: String? = null,
     e: Throwable? = null,

AnkiDroid/src/main/java/com/ichi2/anki/exception/SystemStorageException.kt

@@ -0,0 +1,59 @@
+/*
+ *  Copyright (c) 2025 David Allison <[email protected]>
+ *
+ *  This program is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free Software
+ *  Foundation; either version 3 of the License, or (at your option) any later
+ *  version.
+ *
+ *  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License along with
+ *  this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.ichi2.anki.exception
+
+import android.os.Environment
+import timber.log.Timber
+
+/**
+ * A failure when Android is unable to provide a storage path
+ *
+ * For issue #13207: special handling when `getExternalFilesDir` is `null`
+ * Commonly triggered by an `Android/data` directory corruption bug on Pixel phones:
+ * https://issuetracker.google.com/issues/460912704
+ *
+ * @see [StorageAccessException] for issues with a known storage path
+ */
+class SystemStorageException private constructor(
+    errorDetail: String,
+    val externalStorageState: String,
+    val infoUri: String?,
+) : IllegalStateException("$errorDetail. Media state: $externalStorageState") {
+    override val message: String
+        get() = super.message!!
+
+    companion object {
+        fun build(
+            errorDetail: String,
+            infoUri: String? = null,
+        ): SystemStorageException {
+            val storageState =
+                try {
+                    Environment.getExternalStorageState()
+                } catch (e: Exception) {
+                    Timber.w(e, "getExternalStorageState")
+                    "ERROR"
+                }
+
+            return SystemStorageException(
+                errorDetail = errorDetail,
+                externalStorageState = storageState,
+                infoUri = infoUri,
+            )
+        }
+    }
+}

AnkiDroid/src/main/java/com/ichi2/anki/servicelayer/ScopedStorageService.kt

@@ -36,6 +36,8 @@ object ScopedStorageService {
      *   [com.ichi2.anki.ui.windows.managespace.isInsideDirectoriesRemovedWithTheApp].
      *
      * @return `true` if AnkiDroid is storing user data in a Legacy Storage Directory.
+     *
+     * @throws com.ichi2.anki.exception.SystemStorageException if `getExternalFilesDir` returns null
      */
     fun isLegacyStorage(context: Context): Boolean = isLegacyStorage(CollectionHelper.getCurrentAnkiDroidDirectory(context), context)