{"record":{"id":"5cfdcbe150d9c5b4","repo":"microg/GmsCore","slug":"initialization-failed","errorCode":null,"errorMessage":"Initialization failed","messagePattern":"Initialization failed","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"play-services-auth-api-phone/core/src/main/kotlin/org/microg/gms/auth/phone/SmsRetrieverCore.kt","lineNumber":99,"sourceCode":"                intentFilter.priority = 999\n                smsBroadcastReceiver = SmsReceiver()\n                context.registerReceiver(smsBroadcastReceiver, intentFilter)\n            }\n        }\n    }\n\n    private suspend fun ensureReady(permissions: Array<String>): Boolean {\n        if (SDK_INT < 19) throw RuntimeException(\"Version not supported\")\n        if (!ensurePermission(permissions)) return false\n        configureBroadcastListenersIfNeeded()\n        return true\n    }\n\n    suspend fun startSmsRetriever(packageName: String) {\n        val appHashString = getHashString(packageName)\n\n        if (!ensureReady(arrayOf(RECEIVE_SMS)))\n            throw RuntimeException(\"Initialization failed\")\n        if (anyOtherPackageHasHashString(packageName, appHashString))\n            throw RuntimeException(\"Collision in hash string, can't use SMS Retriever API\")\n        if (requests.values.any { it.packageName == packageName && it.appHashString == appHashString && it.type == RETRIEVER })\n            throw RuntimeException(\"App already listening\")\n\n        val request = SmsRetrieverRequest(\n            id = requestIdCounter.incrementAndGet(),\n            type = RETRIEVER,\n            packageName = packageName,\n            appHashString = appHashString,\n            timeoutPendingIntent = getTimeoutPendingIntent(context, packageName)\n        )\n        requests[request.id] = request\n        alarmManager.set(AlarmManager.RTC, request.creation + TIMEOUT, request.timeoutPendingIntent)\n    }\n\n    suspend fun startWithConsentPrompt(packageName: String, senderPhoneNumber: String?) {\n        if (!ensureReady(arrayOf(RECEIVE_SMS, READ_CONTACTS)))","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/microg/GmsCore/blob/157c9d86ac46c195a86c2f15ab55c84036223f95/play-services-auth-api-phone/core/src/main/kotlin/org/microg/gms/auth/phone/SmsRetrieverCore.kt#L81-L117","documentation":"startSmsRetriever throws 'Initialization failed' when ensureReady(arrayOf(RECEIVE_SMS)) returns false — i.e. the RECEIVE_SMS permission could not be granted (or the SDK check passed but permission acquisition failed). ensureReady returns false rather than throwing when ensurePermission fails, and the caller converts that into a RuntimeException.","triggerScenarios":"Calling startSmsRetriever() when the calling app has not been granted android.permission.RECEIVE_SMS and the library cannot obtain it (permission not declared in the app manifest, or user has denied it).","commonSituations":"Forgetting to declare RECEIVE_SMS in AndroidManifest.xml; user revoked the permission in Settings; targeting Android 6.0+ where permissions must be granted at runtime and the app never requested them.","solutions":["Declare <uses-permission android:name=\"android.permission.RECEIVE_SMS\"/> in AndroidManifest.xml","Request RECEIVE_SMS at runtime with ActivityCompat.requestPermissions before calling startSmsRetriever","Check ContextCompat.checkSelfPermission(this, RECEIVE_SMS) == PERMISSION_GRANTED beforehand and handle denial gracefully","Consider the SMS User Consent API or SMS Retriever via Play Services so RECEIVE_SMS is not needed"],"exampleFix":"// before\nscope.launch { core.startSmsRetriever(packageName) }\n// after\nif (ContextCompat.checkSelfPermission(ctx, Manifest.permission.RECEIVE_SMS) == PackageManager.PERMISSION_GRANTED) {\n    scope.launch { core.startSmsRetriever(packageName) }\n} else {\n    ActivityCompat.requestPermissions(activity, arrayOf(Manifest.permission.RECEIVE_SMS), REQ)\n}","handlingStrategy":"validation","validationCode":"val granted = ContextCompat.checkSelfPermission(ctx, Manifest.permission.RECEIVE_SMS) == PackageManager.PERMISSION_GRANTED","typeGuard":null,"tryCatchPattern":"try { core.startSmsRetriever(pkg) } catch (e: RuntimeException) { if (e.message == \"Initialization failed\") requestPermissions(arrayOf(RECEIVE_SMS), REQ) else throw e }","preventionTips":["Declare RECEIVE_SMS in AndroidManifest.xml","Request the permission at runtime before starting retrieval","Handle onRequestPermissionsResult denial without calling the API"],"tags":["android","sms-retriever","permissions","receive-sms"],"backgroundTag":"permission-denied","analyzedSha":"157c9d86ac46c195a86c2f15ab55c84036223f95","analyzedAt":"2026-09-06T17:27:33.892Z","contentChangedAt":"2026-09-06T17:27:33.892Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}