From 02ab14c73457282eb1c16d21f975399520d8ae1f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mikl=C3=B3s=20Fazekas?= <mfazekas@szemafor.com>
Date: Tue, 3 Mar 2026 15:42:44 +0100
Subject: [PATCH 1/2] docs: add RiveRuntime Android initialization API to error
 handling page

---
 runtimes/react-native/error-handling.mdx | 31 ++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/runtimes/react-native/error-handling.mdx b/runtimes/react-native/error-handling.mdx
index 9a0c7916..82f226c2 100644
--- a/runtimes/react-native/error-handling.mdx
+++ b/runtimes/react-native/error-handling.mdx
@@ -88,3 +88,34 @@ import { RiveView, RiveErrorType } from "@rive-app/react-native";
   If no `onError` handler is provided, errors will be logged to the console by
   default.
 </Note>
+
+### Android Runtime Initialization
+
+On Android, the Rive native library is automatically initialized at app startup. In rare cases (ABI mismatch, missing native libraries, etc.), this initialization can fail. Use `RiveRuntime.getStatus()` to check whether initialization succeeded:
+
+```ts
+import { RiveRuntime } from '@rive-app/react-native';
+
+const { isInitialized, error } = RiveRuntime.getStatus();
+if (!isInitialized) {
+  console.error('Rive failed to initialize:', error);
+}
+```
+
+If initialization failed, you can attempt to re-initialize manually:
+
+```ts
+try {
+  await RiveRuntime.initialize();
+} catch (e) {
+  console.error('Manual initialization failed:', e);
+}
+```
+
+<Note>
+On iOS, the runtime requires no explicit initialization — `getStatus()` will always return `{ isInitialized: true }`.
+</Note>
+
+<Warning>
+**Advanced:** If you need full control over when initialization happens, you can disable automatic initialization by adding `Rive_RiveRuntimeAndroidSkipSetup=true` to `android/gradle.properties`. This is not recommended for most apps — only use this if you have a specific reason to defer initialization.
+</Warning>

From aa86aaff614d57afa625f161ad0820a85d432402 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mikl=C3=B3s=20Fazekas?= <mfazekas@szemafor.com>
Date: Tue, 3 Mar 2026 15:46:23 +0100
Subject: [PATCH 2/2] docs: remove re-init recommendation, mention initialize()
 only for manual setup

---
 runtimes/react-native/error-handling.mdx | 12 +-----------
 1 file changed, 1 insertion(+), 11 deletions(-)

diff --git a/runtimes/react-native/error-handling.mdx b/runtimes/react-native/error-handling.mdx
index 82f226c2..8fa837ab 100644
--- a/runtimes/react-native/error-handling.mdx
+++ b/runtimes/react-native/error-handling.mdx
@@ -102,20 +102,10 @@ if (!isInitialized) {
 }
 ```
 
-If initialization failed, you can attempt to re-initialize manually:
-
-```ts
-try {
-  await RiveRuntime.initialize();
-} catch (e) {
-  console.error('Manual initialization failed:', e);
-}
-```
-
 <Note>
 On iOS, the runtime requires no explicit initialization — `getStatus()` will always return `{ isInitialized: true }`.
 </Note>
 
 <Warning>
-**Advanced:** If you need full control over when initialization happens, you can disable automatic initialization by adding `Rive_RiveRuntimeAndroidSkipSetup=true` to `android/gradle.properties`. This is not recommended for most apps — only use this if you have a specific reason to defer initialization.
+**Advanced:** If you need full control over when initialization happens, you can disable automatic initialization by adding `Rive_RiveRuntimeAndroidSkipSetup=true` to `android/gradle.properties` and calling `RiveRuntime.initialize()` yourself. This is not recommended for most apps — only use this if you have a specific reason to defer initialization.
 </Warning>