Troubleshooting

Troubleshoot Generated Modules

Use this page for files, links, exports, and runtime integration created by the generator.

The generator says this is not a plugin root

The generator does not search parent directories. Run it from the existing plugin directory containing:

PluginConfig.json
package.json
android/
android/settings.gradle       # or settings.gradle.kts

If those files do not exist, create and build the plugin using the official Supernote guide before running this tool.

Add failed during npm or Yarn linking

Read the final rollback or recovery lines first. The generator uses the package manager indicated by the plugin's lockfile.

If both package-lock.json and yarn.lock exist, rerun Add with an explicit choice:

supernote-module add my-module --type native --package-manager npm --yes

Use yarn instead when that is the plugin's intended manager. Do not delete .supernote-module-transaction.json while recovery is pending.

The generated package cannot be imported

Confirm the generator added and linked the local dependency:

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

Expected dependency value:

file:./local_modules/my-module

If Add used --skip-install, run the existing plugin's npm or Yarn install command, then validate the generated module again.

The generated TypeScript declaration is stale

Import generated modules with the default export:

import MyModule from 'my-module';

Native declarations are regenerated by the Android/KSP build after export changes. Run:

supernote-module validate my-module --build --verbose

Confirm package.json points main/react-native to index.js and types to index.d.ts.

Validate reports a link failure

Run verbose validation and fix the first generated file or link it reports:

supernote-module validate my-module --build --verbose

Common causes are a missing file: dependency in your plugin, a stale node_modules link, a missing Native settings block, or a hand-edited generated Gradle file. Update can recreate generated files without replacing your implementation.

Doctor reports CMake or NDK failure

supernote-module doctor --type jni

JNI/JSI generation expects CMake 3.22.1+ and NDK Clang support for C23 and C++23 targeting aarch64-linux-android27. Doctor reports the exact missing generator prerequisite or failed compiler probe.

A Kotlin or Java export is missing

Check generator-specific rules:

• import this module's generated SupernoteExport annotation;
• use a public instance method on a concrete public class;
• use only supported parameter and return types;
• provide a supported constructor;
• keep export names unique.

Then regenerate and compile-check:

supernote-module validate my-module --build --verbose

A C++ export is missing

The marker must be immediately before a top-level definition in .cc, .cpp, or .cxx. Use only supported by-value types, name every parameter, and keep export names unique. C files may provide helpers but cannot export.

supernote-module validate my-jni-module --build --verbose

The build inventories sources and regenerates bindings before CMake compilation.

A generated JNI call cannot find its native method

Do not add handwritten JNI symbols. Common causes are stale generated bindings, an unsupported function signature, or failed native registration.

Run validate --build --verbose, then inspect your plugin's logs for the generated SupernoteNative<JavaScriptName> tag.

A generated JSI function is undefined

Run validate --build --verbose, then inspect your plugin's logs for the generated SupernoteJsi<JavaScriptName> tag. Relevant generator failures mention library lookup, host libjsi.so, nativeInstall, runtime-pointer, or HostFunction installation.

The generated JSI .so is denied execution

dlopen ... Permission denied or avc: denied { execute } means the device or PluginHost blocked the library; it is not an export-marker or generation failure. The tested enforcing retail configuration blocks execution from the extracted location.

Use Native/JNI or obtain PluginHost/firmware support for an executable library location. The generator cannot change linker namespaces or SELinux policy.

Update would overwrite a changed file

Update has no dry-run or file-by-file diff. Commit first, then inspect the module's .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 so startup recovery can read .supernote-module-transaction.json. Exit code 3 means manual recovery is still required. Follow the one printed action and preserve the journal while investigating.

Compare files updated by the generator in package.json, lockfiles, Android settings, local_modules/, and node_modules/ with version control before editing files manually.