[Bug] PluginLoadException: Unable to load io.ionic.backgroundrunner.plugin.BackgroundRunnerPlugin on Android with Capacitor 7.2.0

[joinsnow-star]

1. Plugin Version:
@capacitor/background-runner: v2.1.0

2. Capacitor Version:
@capacitor/core: v7.2.0
@capacitor/android: v7.2.0
@capacitor/cli: v7.2.0

3. Problem Description:
The @capacitor/background-runner plugin fails to load on the Android platform when the application starts. The primary error observed in Logcat is:
NativePlugin io.ionic.backgroundrunner.plugin.BackgroundRunnerPlugin failed to load com.getcapacitor.PluginLoadException: Unable to load plugin instance. Ensure plugin is publicly accessible at com.getcapacitor.PluginHandle.load(PluginHandle.java:107) at com.getcapacitor.PluginHandle.<init>(PluginHandle.java:65) at com.getcapacitor.Bridge.registerPlugin(Bridge.java:701) at com.getcapacitor.Bridge.registerAllPlugins(Bridge.java:657) at com.getcapacitor.Bridge.<init>(Bridge.java:231) at com.getcapacitor.Bridge$Builder.create(Bridge.java:1595) at com.getcapacitor.BridgeActivity.load(BridgeActivity.java:48) at com.getcapacitor.BridgeActivity.onCreate(BridgeActivity.java:42) at com.MRtenfingers.fantasytimer.MainActivity.onCreate(MainActivity.java:16) // App package name and MainActivity // ... (Full Java stack trace can be attached if requested)

This native plugin load failure leads to subsequent errors in the JavaScript layer:

[background-runner-bridge] BackgroundRunner plugin is unavailable [timer-controller] BackgroundRunner initialization failed [timer-controller] Timer controller not initialized

as a result, any functionality relying on the background runner (e.g., starting a timer) fails.

4. Steps to Reproduce:
The issue was reproduced in a minimal Capacitor project:

1. Initialized a new Capacitor project (npm init -y, npm install @capacitor/cli@^7.2.0 @capacitor/core@^7.2.0 @capacitor/android@^7.2.0, npx cap init TestApp com.example.testapp, npx cap add android).
2. Installed only @capacitor/background-runner@2.1.0 (npm install @capacitor/background-runner@2.1.0).
3. Created a minimal www directory with an index.html and a basic js/app.js that attempts to check Capacitor.isPluginAvailable('BackgroundRunner') and access Capacitor.Plugins.BackgroundRunner on deviceready.
4. Ensured capacitor.config.ts had webDir: 'www'.
5. Ran npx cap sync android.
6. Built and ran the application on an Android device/emulator using Android Studio.
7. Observed the same PluginLoadException for io.ionic.backgroundrunner.plugin.BackgroundRunnerPlugin in Logcat upon app startup.

5. Expected Behavior:
The @capacitor/background-runner plugin should load and initialize successfully with Capacitor 7.2.0 on Android, allowing its JavaScript API to be used.

6. Actual Behavior:
The plugin fails to load at the native Android level with a PluginLoadException, making it unusable from the JavaScript side.

7. Troubleshooting Steps Taken (in both main project and minimal reproduction):

• Verified that the plugin's peerDependencies ("@capacitor/core": "^6.0.0 || ^7.0.0") theoretically support Capacitor 7.2.0.
• Confirmed npx cap sync android detects the plugin (Found 5 Capacitor plugins for android: @capacitor/background-runner@2.1.0 ...).
• Ensured android/capacitor.settings.gradle correctly includes :capacitor-background-runner and its projectDir.
• Ensured android/app/build.gradle has the implementation project(':capacitor-background-runner') dependency.
• Confirmed the repositories { flatDir { ... } } in android/app/build.gradle points to ../../node_modules/@capacitor/background-runner/android/src/main/libs, and the android-js-engine-release.aar file exists at this location.
• Verified the plugin's own build.gradle (node_modules/@capacitor/background-runner/android/build.gradle) declares a dependency on android-js-engine-release.aar via implementation(name: "android-js-engine-release", ext: "aar").
• Confirmed the plugin's Kotlin file (.../io/ionic/backgroundrunner/plugin/BackgroundRunnerPlugin.kt) has the package and class name (io.ionic.backgroundrunner.plugin.BackgroundRunnerPlugin) that Logcat indicates Capacitor is trying to load.
• Ensured MainActivity.java does not contain manual this.init() calls for plugin registration, relying on Capacitor's automatic loading (consistent with Capacitor 4+ best practices).
• Performed thorough project cleanups: Android Studio's "Invalidate Caches / Restart" and manual deletion of android/build and android/.gradle folders.

8. Environment Details:

• Capacitor Core Version: ^7.2.0
• Capacitor Android Platform Version: ^7.2.0
• Capacitor CLI Version: ^7.2.0
• @capacitor/background-runner Version: 2.1.0
• Node.js Version: [Your Node.js Version, e.g., v18.16.0]
• NPM Version: [Your NPM Version, e.g., 9.5.1]
• Development OS: [Your OS, e.g., Windows 10, macOS Sonoma]
• Test Device/Emulator: [Your Test Device and Android Version, e.g., Pixel 6 Android 13 / Xiaomi MIUI 14 Android 13]
• Android Studio Version: [Your Android Studio Version, e.g., Giraffe | 2022.3.1 Patch 2]
• Android Gradle Plugin Version (from root android/build.gradle): [e.g., com.android.tools.build:gradle:8.x.x]
• Gradle Version (from android/gradle/wrapper/gradle-wrapper.properties): [e.g., distributionUrl=https://services.gradle.org/distributions/gradle-8.x-bin.zip]

9. Potentially Relevant Files (Can provide if needed):

• package.json
• android/capacitor.settings.gradle
• android/app/build.gradle
• node_modules/@capacitor/background-runner/android/build.gradle
• Logcat output from the minimal reproduction project.

Questions for the Plugin Maintainers:

• Are there any known compatibility issues or specific configuration steps required for @capacitor/background-runner@2.1.0 when used with @capacitor/core@7.2.0 and @capacitor/android@7.2.0?
• Could the bundled android-js-engine-release.aar have compatibility issues with newer Android versions, build tools, or specific CPU architectures that might lead to this PluginLoadException?
• Is there a more recent version of @capacitor/background-runner recommended for use with Capacitor 7?

Thank you for your time and any assistance you can provide.