Troubleshooting JCVaultListener

We ask that you read this troubleshooting guide first and follow its advice before posting questions or submitting trouble tickets. It isn't that we don't want to help you, but frankly and very bluntly, 99% of problems encountered are due to pilot errors (that means you) - using outdated plugins, improper configurations, and such; to name a few.

JCVaultListener is a simple plugin. Even though it has several configuration items, they mostly are for formatting and displaying message responses to votes. There are no configuration settings that will prevent JCVaultListener from processing a voting event. However, it doesn't do much good to have this plugin, or other vote listeners, if you didn't configure Votifier properly.

Vote Overview

The figure above depicts a high-level overview of the voting process. A user visits a voting service such as Minestatus to submit a vote, which causes a vote record to be created that among other things contains the user's IGN - in-game-name. The record is encrypted by the voting service and sent to the CraftBukkit server for which the vote is intended. The public key for encryption, server IP address, and port number used to send vote notifications were configured by the server admin while registering their server with the voting service.

If everything is configured properly, Votifier receives and decrypts the vote notification. Thereupon, it calls voteMade() methods for any registered vote listener classes and also posts a VotifierEvent event to CraftBukkit's main server thread. JCVaultListener, and possibly other plugins, watches for such events and processes votes accordingly.

Votifier & JCVaultListener

If you are not receiving votes then there is a configuration error somewhere. It could be with the voting service, Votifier, or even your hosting provider if you are running a server on a VPS/shared hosting service. Please understand that we are talking about configurations outside the scope of JCVaultListener; but since it needs a properly configured Votifier, we'll give you a few pointers that will hopefully help you help yourself in finding the problem.

Learn To Read Server Logs

All good plugin developers design plugins that provide additional diagnostic information to help you figure out what is happening when problems are encountered - Votifier and JCVaultListener are no exception. Learn to read server logs and be able to identify which plugins are reporting problems.

Severity Levels

Your logs generally contain entries with one of the following three severity levels:

• [INFO] - General information about a plugin, options that are enabled, decisions made, etc. A properly configured server will mostly show [INFO] messages though there may be a smattering of [WARNING] messages too.
• [WARNING] - Warnings are not necessarily errors and are intended to draw your attention to some condition(s). For example, plugins that check for updates might issue warnings if newer versions are available. Plugins might also issue warnings about non-critical mis-configurations and announce that they might be running in a degraded state.
• [SEVERE] - These entries call you attention to serious problems. A plugin may not be able to find other plugins that it depends upon; some assumed conditions didn't pan out to be true; serious configuration errors are detected; and such. In many cases, such errors are accompanied by a stack trace showing where errors occurred and what methods were involved.

Plugin Identifiers

In addition to severity levels, most plugins will add their own identifier to the entry. For example, the entry

2012-05-31 17:43:09 [INFO] [JCVaultListener] Enabled!

is an informational entry showing that JCVaultListener was enabled successfully. Other entries may have longer messages and possibly include stack traces; but you should always look for the plugin identifier to make sure which plugin may be reporting problems.

Stack Traces

It is understood that most of you are not programmers and stack traces may seem like a foreign language to you; but, here are some highlights to help you make sense of them. Take the following log entries:

2012-06-04 22:24:21 [INFO] [Votifier] Enabling Votifier v1.6
2012-06-04 22:24:21 [INFO] [Votifier][VaultListener 1.1.4] Using economy plugin: iConomy 6
2012-06-04 22:24:21 [INFO] Loaded vote listener: VaultListener
2012-06-04 22:24:21 [SEVERE] [Votifier] Unable to enable Votifier.
java.lang.ClassNotFoundException:
   at java.net.URLClassLoader$1.run(Unknown Source)
   at java.net.URLClassLoader$1.run(Unknown Source)
   at java.security.AccessController.doPrivileged(Native Method) at java.net.URLClassLoader.findClass(Unknown Source)
   at java.lang.ClassLoader.loadClass(Unknown Source)
   at java.lang.ClassLoader.loadClass(Unknown Source)
   at com.vexsoftware.votifier.model.ListenerLoader.load(ListenerLoader.java:34)
   at com.vexsoftware.votifier.Votifier.onEnable(Votifier.java:100)
   at org.bukkit.plugin.java.JavaPlugin.setEnabled(JavaPlugin.java:215)
   at org.bukkit.plugin.java.JavaPluginLoader.enablePlugin(JavaPluginLoader.java:337)
   at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:381)
   at org.bukkit.craftbukkit.CraftServer.loadPlugin(CraftServer.java:256)
   at org.bukkit.craftbukkit.CraftServer.enablePlugins(CraftServer.java:238)
   at org.bukkit.craftbukkit.CraftServer.reload(CraftServer.java:552)

Stack traces list methods in reverse order from the point of error origination to the topmost method calling it. In this case, CraftServer's reload() method calls enablePlugins(), which called loadPlugin(), and so on, all the way down to URLClassLoader$1.run(). The last method is part of a series of Java runtime methods. Obviously, you already know which plugin had the problem - Votifier. Why? Because you read the plugin identifier right after the severity level.

Assume for a moment that no identifier is presented. How can you figure out what plugin is having problems? You work your way down the trace till you find the first entry that contains the name of one of your plugins. In this case, that would be

   at com.vexsoftware.votifier.model.ListenerLoader.load(ListenerLoader.java:34)

which shows that the error happened while Votifier was calling the load() method of its ListenerLoader class. Looking at a stack trace in this fashion isn't foolproof. It is entirely possible that a plugin may call functions of another plugin improperly or with bad data. You should always look further down the trace to see if there are any other plugins involved. But in this case, you didn't have to go through that trouble, because the plugin was already identified at the beginning.

Verify that Votifier and JCVaultListener are installed

Common sense, but you'd be surprised how many admins install one but not the other.

Verify that you have the right versions and that they enable successfully

To use JCVaultListener 2.0, you must have Votifier 1.8 or better. How do you find out which version you have? Check at the beginning of your log session. CraftBukkit loads all plugins first before starting them up. You should find a group of loading messages, which will also contains those for Votifier and JCVaultListener

...
2012-05-31 20:07:16 [INFO] [Votifier] Loading Votifier v1.8
...
2012-05-31 20:07:16 [INFO] [JCVaultListener] Loading JCVaultListener v2.0
...

In addition to loading messages, you should find more plugin-specific messages further down the log. Vertify that report version numbers are the one that you expect.

...
2012-05-31 20:07:19 [INFO] [Votifier] Enabling Votifier v1.8
...
2012-05-31 20:07:19 [INFO] [Votifier] Enabled.
...
2012-05-31 20:07:21 [INFO] [JCVaultListener] Enabling JCVaultListener v2.0
...
2012-05-31 20:07:21 [INFO] [JCVaultListener] Enabled
...

Check Your IP Address and Port Number

Make sure that the IP address (host:) and port number (port:) configured for Votifier are available for your use. This is a very common problem!! Unless you have a unique hosting setup, Votifier's host: configuration item should be set to the same IP address as the server. If you are using a fully qualified domain name, make sure that it resolves to the expected IP address (e.g. nslookup).

Port numbers can be a different story. If you are running a private server on a home network or on a company server behind a firewall, you need to make sure that the firewall forwards requests on that port to the same port on your server. If you firewall is using PAT (Port Address Translation), voting services need to be configured to send votes your public port value, but Votifier needs to be configured to receive on your internal port.

If your server is installed on a VPS/shared hosting services, you must contact your hosting service to find out what, if any, port numbers are available for your use. While Votifier uses the default port 8192, you should not assume that it is available to you; another CraftBukkit server may already be using it. Seriously, check with your provider!

Turn On Debug Mode and Send Test Notifications

Turn on Votifier's debug mode by adding

debug: true

to its configuration file. Doing so will cause Votifier to dump vote notifications to the server log. Go to your voting site and use its test feature to send a vote. If everything is configured right, you should see the vote record in your logs. It should be noted that not all voting sites send test votes. Some simply check if they can connect to the IP address and port you've configured considering that good enough as validation. Obviously, that's only half the picture. Your best bet is to use Minestatus. It sends a dummy vote record with the IGN of Test Notification.

JCVaultListener

While the previous section touched upon JCVaultListener, it mostly dealt with Votifier configurations. If you are at a point where you know that Votifier is work and receiving votes, now it is a matter of whether you've got JCVaultListener configured properly. In most cases, it barks at you if it can't initialize properly. Below is a list of warnings and error messages you might encounter.

Errors You Might Get

Could not find Vault API. Please make sure Vault is installed and enabled!

The Vault plugin is missing or failed to initialize properly. JCVaultListener will still receive votes, thank the player and broadcast it to the server (if enabled), but no payments will be made.

Vault cannot detect a valid economy plugin. No payments will be made!

As stated, Vault did not find a compatible economy plugin. You should look at log entries to make sure that your economy plugin is loaded and enabled. Furthermore, you should check Vault log entries and see what, if any, economy plugin it detected.

Please make sure to delete the old 'VaultListener.class' from Votifier's listener directory and/or 'VaultListener.properties' from the data directory!

On its first run, JCVaultListener will attempt to import settings from the old VaultListener's properties file. Thereafter, it will issue this warning to remind you to uninstall VaultListener. Simply delete the VaultListener.class file from Votifier's listeners directory and remove VaultListener.properties from its data directory. If you don't, your players will get double rewards.

Cannot deposit negative funds

This Vault-specific error indicates that you have configured a negative reward amount. Malicious admin, perhaps?

Errors You Should Never Get

Unable to import old VaultListener properties. Using default configuration!

JCVaultListener ran into a problem while reading the old properties configuration file. If this happens, you will have to manually edit JCVaultListener's config.yml file to set options as you expect.

Unable to create JCVaultListener data folder!
Unable to save configuration file!

Something is wrong with your server's file system. You could be running out of disk space or have a corrupt hard drive.

Unable to read configuration template. Configuration file will not be saved!

Chances are that JCVaultListener is corrupted or someone mucked with its internals. Download a fresh copy and reinstall.

If All Else Fails

If nothing still makes sense, we'd certainly like to hear about it. Certainly, there is no claim that JCVaultListener is bullet-proof; all it can do is to try to be as robust as it can. But then again it is possible that something wasn't as obvious as it was first deemed to be. As long as there are human beings involved somewhere in the chain of things that must happen for a CraftBukkit server to work, problems can happen.

When they do, please feel free to submit a ticket under JCVaultListener's Issue Tracker. Please include the following:

• A stack trace of any uncaught exception related to JCVaultListener. Please make sure to include 4-5 log entries prior to the stack trace.
• If possible, try to run JCVaultListener in a minimum environment. For example, disable all plugins except: Votifier, Vault, and whatever economy plugin you are using. If the problem persists, we certainly should hear about it.