Platform > Plugins

Troubleshooting Plugins

This page lists plugin problems by what you see: a missing log line, a server that will not start, or a plugin that fails when used. Each entry gives the exact message, the cause, and the fix.

The startup log, log/AmiCore.log, records every bundle in 3 stages. Finding the last stage a bundle reached narrows down the cause:

1. LOADING BUNDLE <path> WITH NAME <file> (...): the server found and read the file.
2. REGISTERED PLUGIN: <TYPE>><ID> (...) FROM BUNDLE <file>: the server found a plugin inside it.
3. CREATED PLUGIN: <TYPE>><ID> (...): a component enabled the plugin. This line appears once for each component that uses the plugin.

log/AmiCore.log always holds the current run. Each restart renames the previous log to log/AmiCore.0001.log, log/AmiCore.0002.log, and so on, so check the file's timestamps when comparing runs.

No LOADING BUNDLE line for a bundle

If the log has no LOADING BUNDLE line for a bundle, the server never read the file. There is no error message for any of these causes, so check each one:

• The server was not restarted after the file was copied in. Plugins are read only at startup.
• The file is not in a scanned directory. The default is the installation's plugins/ directory, set by ami.plugins.dir. A directory listed there that does not exist is skipped silently.
• There is a space after a comma in ami.plugins.dir. The location after the space is ignored. Remove the space.
• The file extension is not .tar.gz, .zip, or .jar. Other files, including .tgz and .tar, are ignored.
• ami.plugins.dir is empty or not set. The log then says MISSING ami.plugins.dir PROPERTY SO EXTERNAL PLUGINS WILL NOT BE LOADED.

The bundle loaded but the plugin is not listed as enabled

If the log shows LOADING BUNDLE and REGISTERED PLUGIN but no CREATED PLUGIN line, the plugin is registered but no component enabled it. The plugin list for its type does not include it:

• The list excludes it: look for ! followed by the plugin's ID.
• The list does not contain * and does not name the ID.
• The list is empty or not set, which enables nothing. For AmiScript library plugins this is the shipped state; see Enabling and disabling plugins.

ami.showPlugins() on the admin console shows the governing list in its ManagerProperty column for plugins of the same type. See Checking installed plugins.

A Relay plugin is missing from SHOW PLUGINS

SHOW PLUGINS on the Center SQL console lists Center plugins only, so a feed handler or other Relay plugin never appears in it, even when enabled. Check with ami.showPlugins() on the admin console instead.

The server will not start after a plugin change

The server exits during startup when a plugin list or the plugins directory is inconsistent. The last line of error.log, in the installation root, then reads:

EXITING WITH CODE 3.  Unknown Error: RuntimeException

The cause is in log/AmiCore.log, in one of the messages below. In the log each message follows a java.lang.RuntimeException: or exception_text: prefix, so search for the message text itself.

Plugin not found

Error processing property ami.relay.feedhandler.plugins=*,KAFKA
Plugin not found: KAFKA  (available RELAY_FEEDHANDLER plugins: AMI_RTCLIENT,AMI_RTSERVER)

A plugin list names an ID that is not registered. The cause is a typo, a difference in case (IDs are case-sensitive), or a removed bundle, as in this example. The message lists every registered ID for the type, including those from installed bundles; correct the entry or remove it.

The same plugin class exists twice or The same plugin ID exists twice

Error processing Plugin: amikafka_old.tar.gz
The same plugin class exists twice: RELAY_FEEDHANDLER>KAFKA (... loaded from amikafka.tar.gz ==> ...) vs RELAY_FEEDHANDLER>KAFKA (... loaded from amikafka_old.tar.gz ==> ...)

Two bundles contain the same plugin, usually because an upgrade left the old file in place. The message names both files. Delete one and start again.

Unable to create plugin for class

A plugin in a plugin list failed while starting. The log shows INIT PLUGIN FAILED: or CREATE PLUGIN FAILED: with the plugin's name and the underlying error just before this line. The fix depends on that plugin.

3forge AMI is already running at this location

EXITING WITH CODE 2.  3forge AMI is already running at this location

A second start was attempted while the server from the same installation was still running, usually because a restart did not wait for the old process to exit. The running server is unaffected. Wait until it has stopped, then start it again.

A plugin fails the first time it is used

NoClassDefFoundError or ClassNotFoundException naming a class from the plugin's own libraries

The bundle was extracted into the plugins directory, so each of its jars loaded separately and the plugin cannot see its libraries. For the Kafka feed handler the message is:

java.lang.NoClassDefFoundError: org/apache/kafka/common/errors/WakeupException

Stop the server, delete the extracted files, copy the original archive into plugins/, and start the server. Stop it first: on Windows the running server keeps the extracted jars open, and if the archive is copied back while they remain, the next start fails with The same plugin class exists twice. See Why a bundle must not be extracted.

DROPPING DUPLICATE CLASS AT ... META-INF/versions/... at startup

This line means a bundle contains a jar with separate class versions for different Java releases, and the server kept one version of each class without choosing by Java release. The plugin may fail when used, with a NoClassDefFoundError or Could not initialize class error. Contact the plugin's supplier for a bundle built for your server.

Access denied by ami_<component>: <path> not in Permitted dirs (<dirs>)

The plugin tried to read a file outside the directories the server is allowed to access. This is not a plugin setting: the allowed directories are set by ami.component.allowed.dirs, which defaults to the server's working directory.

To allow the plugin to read a directory, add it to ami.component.allowed.dirs in config/local.properties as a comma-separated list. Include the installation directory as well, because setting the property replaces the default rather than adding to it.

Expected warnings at startup

Some plugin warnings appear on every startup and do not indicate a problem:

• REGISTERED PLUGIN: GATEWAY_FILTER>SAMPLE_GATEWAY_FILTER_PLUGIN (...) WITH MISSING @AmiPluginAttribute: a sample plugin built into the server.
• SECURITY-WARNING: PLUGIN ... for DATASOURCE>SHELL, REST>QUERY, AUTH>ACCESS_FILE, and DATASOURCE>FLAT_FILE: these describe what each plugin can access. SHELL and QUERY are registered but excluded by the shipped configuration. See Security warnings from plugins.

What this page does not cover

• Problems inside a working plugin, such as a feed handler that connects but receives no data: these are specific to each plugin.
• Server startup failures unrelated to plugins: see the Operations troubleshooting page.