Troubleshooting

Troubleshooting

Start at the first failing layer: a linked package is not compiled, a compiled Android library is not a .snplg, a transferred package is not installed, and an installed JSI library may still be blocked by PluginHost or SELinux.

The generator says this is not a plugin root

Run from the exact directory containing PluginConfig.json, package.json, android/, and android/settings.gradle (or .kts). The generator does not search parent directories.

pwd
ls -ld PluginConfig.json package.json android android/settings.gradle*

PowerShell:

Get-Location
Get-Item PluginConfig.json, package.json, android, android\settings.gradle*

If PluginConfig.json is missing from a new official plugin, package the unmodified plugin once.

npm or Yarn installation failed

Read final rollback/recovery output first. Check which manager the plugin uses:

ls package-lock.json yarn.lock 2>/dev/null

Then rerun npm install or yarn install with full output. If both lockfiles exist, select intentionally with --package-manager. Do not delete a reported recovery journal.

The generated package is missing in JavaScript

From the plugin root:

node -p "require('./package.json').dependencies['local-math']"
node -p "require.resolve('local-math/package.json')"

The dependency should be file:./local_modules/local-math. If Add used --skip-install, run the appropriate install command, then rebuild and reinstall.

The TypeScript import fails

Use the generated package's default export:

import Math from 'local-math';

Do not use {Math}. Confirm the package points main/react-native to index.js and types to index.d.ts. The Android build regenerates declarations after export changes.

Gradle cannot find the local package

Prove Node resolution as above, then run the real Android task.

macOS/Linux:

cd android
./gradlew :app:assembleDebug --stacktrace

Windows PowerShell:

Set-Location android
.\gradlew.bat :app:assembleDebug --stacktrace

Return to the plugin root before using its packaging script.

CMake or the NDK is missing

supernote-module doctor --type jni

Check ANDROID_HOME/ANDROID_SDK_ROOT, the installed NDK, and CMake 3.22.1+. The selected NDK Clang must accept C23 and C++23 for aarch64-linux-android27. Doctor probes tools but does not run the full plugin build.

A Kotlin/Java export is missing

Check the module-specific annotation import, public instance method and class, supported types, supported constructor, unique export name, and a fresh build.

supernote-module validate local-math --build --verbose
adb logcat -d -s SupernoteNativeMath:V ReactNativeJS:V '*:S'

A C++ export is missing

Put the marker directly before a top-level definition in .cc, .cpp, or .cxx, use only supported by-value types, name every parameter, and keep export names unique.

supernote-module validate local-math-jni --build --verbose

Rebuild because Gradle inventories sources and regenerates bindings before CMake compilation.

JNI compiles but a call rejects or a native method is missing

adb logcat -d -s SupernoteNativeMathJni:V ReactNativeJS:V '*:S'

Likely causes are a stale installed plugin, changed exports without a full build, an unsupported signature, or generated registration/loading failure. Do not add handwritten JNI symbols.

The plugin builds but does not load

Capture PluginHost and React Native failures:

adb logcat -d | rg -i 'pluginhost|ReactNativeJS|UnsatisfiedLinkError|dlopen|FATAL EXCEPTION|AndroidRuntime'

If rg is unavailable, use your terminal's text search. Verify React Native 0.79.2, arm64 package contents, and that the latest .snplg was reinstalled.

A JSI function is undefined

Rebuild and reinstall, trigger the plugin after initialization, then inspect:

adb logcat -d -s SupernoteJsiMathJsi:V ReactNativeJS:V '*:S'

Look for host libjsi.so, nativeInstall, runtime pointer, library lookup, or HostFunction installation failures.

The JSI .so cannot execute

dlopen ... Permission denied or avc: denied { execute } indicates device policy, not an export-marker problem. The tested enforcing retail configuration blocks extracted JSI libraries. Use Native/JNI or obtain host/firmware support; the generator cannot change SELinux policy.

Update would overwrite changed files

Update has no dry-run. Commit, then inspect .supernote-module.json:

• generated_files may be replaced;
• implementation_roots are preserved by Update;
• the generated README is replaceable;
• Remove deletes the complete package.

See Managing Modules.

Generation stopped halfway

Run the generator again. Startup recovery reads .supernote-module-transaction.json and tries to restore or finalize the transaction. Exit 3 means manual recovery remains. Follow the one printed action and preserve the journal while investigating.

Compare package.json, lockfiles, Android settings, local_modules/, and node_modules/ with version control before manual edits.

Validate passes but packaging or the device fails

Plain Validate proves structure, parent integration, binding generation, and the dependency link. --build adds :app:assembleDebug. Neither runs buildPlugin.sh, checks a .snplg, installs it, or qualifies firmware. Continue at the first unproved layer.