Troubleshooting

Troubleshoot Generated Modules

These symptoms concern files, links, exports, and runtime integration created by the native-module generator. Problems in the surrounding plugin workflow belong in the official Supernote documentation.

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, the prerequisite working plugin is not in scope for this generator.

Add failed during npm or Yarn linking

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

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

supernote-module add local-math --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['local-math']"
node -p "require.resolve('local-math/package.json')"

Expected dependency value:

file:./local_modules/local-math

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

The package has one default export:

import Math from 'local-math';

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

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

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

Validate reports parent integration failure

Run verbose validation and address the first reported generator-owned path:

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

Common causes are a missing parent file: dependency, a stale node_modules link, a missing Native settings block, or a hand-edited generated Gradle file. Update can regenerate owned infrastructure while preserving implementation roots.

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 local-math --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 local-math-jni --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. Likely generator-boundary causes are stale generated bindings, a changed export without regeneration, an unsupported signature, or generated registration/loading failure.

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

A generated JSI function is undefined

Run validate --build --verbose, then inspect the existing 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 } is a target policy failure, 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 generator-managed paths in package.json, lockfiles, Android settings, local_modules/, and node_modules/ with version control before manual edits.