When a Plugin Does Not Load
A symptom-driven guide to diagnosing why a plugin JAR is rejected, does not appear, or does not behave as expected.
Start from what you see. Each section lists the likeliest causes, in the order worth checking them. For installer, startup, and host problems that are not specific to plugins, see Troubleshooting.
First, gather evidence
Before changing anything:
- Open the logs. Choose Turboism → Logs… and look at the current session log. Search for your plugin ID. Failures are reported with the plugin ID attached.
- Check Manage Plugins. Open Turboism → Manage Plugins…. If the plugin is listed, double-click it for its SDK API range and declared Cubism versions.
- Note the versions. Record the Turboism version, the Cubism Editor version, and the exact steps. Version-dependent failures are common.
Do not edit plugin, config, or pending-state files while Turboism is running, and never disable the validation that rejected your JAR.
The JAR is rejected when you install it
Install from JAR… inspects the file first. It can reject a JAR for:
- a symbolic link or non-regular source, or an archive that exceeds the raw-size, entry-size, total-expansion, entry-count, or compression-ratio limits;
- malformed or duplicate entries, special files, or a missing or duplicate
META-INF/turboism/plugin.json; - an ID, version, or API-range mismatch in the descriptor;
- copied SDK, Runtime, test, or Live2D classes: your build must use
compileOnly, not shade the SDK; - native binaries, installer payloads, or nested JARs;
- a missing entrypoint, or an undeclared ordinary resource;
- an i18n catalog declared in
plugin.jsonbut absent from the JAR.
Rebuild from source with ./gradlew clean build and install the JAR that Gradle produced. Do not edit the archive by hand.
It installs but does not appear
Check that:
- the operation was applied after a full restart of Cubism, using the same Turboism home on both launches;
- if you copied the JAR manually, it is directly in the root of
<turboism.home>/plugins/, not a subfolder; - no older JAR with the same plugin ID remains (a duplicate fails with
DUPLICATE_PLUGIN_ID); - the plugin ID is not disabled in Manage Plugins…;
environment.requiresCubismmatches the environment you started;- the entrypoint class exists, is
public, implementsTurboismPlugin, and has a public no-argument constructor; - the descriptor uses a supported
schemaVersionand is valid for it. Unknown fields are rejected rather than ignored, so a typo in a field name fails the load.
It is marked incompatible
Plugin Management and the Plugin Market mark a plugin as incompatible when its turboismApi range does not include the running Turboism API. A legacy [0.1.0,0.2.0) range fails with TURBOISM_API_INCOMPATIBLE. Use [0.67.0,1.0.0) or a higher minimum if you rely on newer SDK members.
It loads, then fails to start
If construction, init, or enable throws, Runtime rolls back the whole JAR, and your exception appears in the log with the plugin ID. Typical causes:
- an unguarded call to an unavailable service (see Permissions and availability);
- a missing localization key or catalog;
- an invalid configuration schema (for example a bad key name, or a duplicate config ID or path);
- a
NullPointerExceptionfrom a field you only set in a method that runs later.
The fix is almost always a guard (isAvailable(), services().find(...)) or a descriptor correction, not a broader permission.
It starts, but a feature does nothing
Work through the four checks in Permissions and availability:
- Permission. Is the permission for the exact call declared in
plugin.json? A refusal is logged against your plugin. - Service. Did
services().find(...)come back empty, or did anunavailable()sentinel respond? - Cubism version. Does the log show
CubismEditorApiUnavailableExceptionor an unavailable API ID? The Editor version may not admit that API; see Compatibility. - State. Is a model document actually active? Is the object you hold stale because the document changed?
Also check that you registered in enable(), enrolled the handle in the disposable scope, and that the plugin is enabled, not just installed.
Structured diagnostics are available through context.diagnostics() if you want to surface runtime-reported problems from inside the plugin.
A menu entry or action is missing
- The menu path is a slash-delimited string. If it comes from a catalog, confirm the key exists in
messages.properties, the base catalog. turboism.action.registerandturboism.ui.menu.contributeare both needed: one for the action, one for the menu entry.- The menu contribution refers to an action ID. A typo in either place leaves a menu item with nothing behind it, or an action with no menu.
A setting does not appear or does not stick
turboism.config.plugin.writeis needed to register a schema, andturboism.config.plugin.readto read it.- Register the schema in
init, before anything reads it, and guard withconfig().isAvailable(). - An editor field's
keymust match a key declared in the schema, and use lowercase[a-z0-9._-]. - Writes use revisions. A stale revision is rejected as a value in the result, not an exception, so inspect the result.
Still stuck
- Reduce the plugin to the smallest version that shows the problem, ideally the Step 2 hello plugin.
- Compare your descriptor with Plugin Manifest and Packaging and a first-party plugin's
plugin.json. - Report a reproducible problem with the versions and log lines through Report a Bug. Remove private paths, credentials, and personal data from anything you share.