Setting up Votifier so vote rewards actually work

Votifier is the plugin that lets a toplist tell your Minecraft server that somebody voted, so the reward lands in their inventory while they are still online. It has been the standard since 2012, it is not complicated, and it fails for about six predictable reasons.

This is how to set it up on VoteRank, and how to diagnose it when nothing arrives.

What actually happens when someone votes

1. A player clicks vote on your listing and completes the captcha.
2. We record the vote and, if you have incentive voting enabled, take the in-game name they typed.
3. We open a TCP connection to your Votifier port, encrypt a small payload with your public key, and send it.
4. Your plugin decrypts it, verifies it, and fires a VotifierEvent.
5. Your reward plugin — VotingPlugin, SuperbVote, whatever you use — listens for that event and gives the reward.

Every failure is one of those five steps not happening. Knowing which one narrows the fix immediately.

Which version to install

NuVotifier is the one to use. The original Votifier is unmaintained and the v1 protocol uses RSA in a way that has aged badly. NuVotifier speaks both v1 and v2, so it works with every toplist including the ones that never updated.

Install it like any plugin: drop the jar in plugins/, restart, and it generates plugins/NuVotifier/config.yml plus an RSA keypair in plugins/NuVotifier/rsa/.

The config lines that matter:

host: 0.0.0.0
port: 8192
disable-v1-protocol: false

tokens:
  default: 'a-long-random-string'

host: 0.0.0.0 matters more than people expect. The default on some builds binds to 127.0.0.1, which means the plugin only accepts connections from the machine itself — and we are not on that machine.

Which protocol to give us

v2 (token) is the better choice. Copy the default token out of config.yml and paste it into the NuVotifier token field on your listing. It is a shared secret, it is a single line, and it does not care about key formatting.

v1 (RSA public key) still works and is what you need if you are running the original Votifier. Open plugins/NuVotifier/rsa/public.key and paste the whole contents into the Votifier public key field. It is one long base64 string — no line breaks, no -----BEGIN PUBLIC KEY----- header. If you paste the private key by mistake, nothing will work and you have leaked the key, so regenerate it.

Fill in one or the other, not both. If both are present we use v2.

Opening the port

This is where most setups fail, and it is not a plugin problem.

Votifier listens on 8192 by default. It is a separate port from the game port — opening 25565 does nothing for it. You need:

• The port open in the machine's firewall (ufw allow 8192/tcp on most Linux hosts).
• The port forwarded, if you are behind a router or NAT.
• The port allowed by your host's control panel.

Shared and budget hosts are the usual obstacle. Many allocate you exactly one port and charge for extra ones, and some block additional ports entirely. If your host will not give you a second port, you have two options: run Votifier on an allocated port you already have that is not in use, or skip Votifier and use the HTTP postback described at the end.

To check whether the port is genuinely reachable from outside, from any machine that is not your server:

nc -vz your-server-ip 8192

succeeded means we can reach it. Connection refused means nothing is listening — the plugin did not start, or it bound to localhost. A hang followed by a timeout means a firewall is silently dropping the packets, which is the most common result and the most misleading, because the plugin logs look perfectly healthy.

Testing it

On your listing's edit page there is a Test connection button. It performs the same handshake a real vote does and tells you what came back. Use it before you tell your players voting is live.

You can also test from the server side with NuVotifier's own command:

/nvreload
/pnv test <yourname>

If /pnv test produces a reward and a real vote does not, the plugin and your reward plugin are both fine — the problem is between us and your port, which means firewall or address.

The six things that are actually wrong

In rough order of frequency:

1. The port is closed. See above. This is more than half of all cases.
2. host is 127.0.0.1. Change it to 0.0.0.0 and restart.
3. Wrong address on the listing. If your Votifier runs on a different address or port than the game server, fill in the Votifier host field. Leave it blank only when they are the same.
4. The key has a stray newline or the PEM header. Paste the base64 body only, as one line.
5. No reward plugin is listening. Votifier only fires an event. Something has to catch it. If /pnv test shows the event firing in console but no reward appears, the gap is your reward plugin's config, not us.
6. The server was offline when the vote happened. Votifier is fire-and-forget over TCP — there is no queue on our side for a server that was down. We retry a failed delivery with backoff for a while, and then the vote still counts for your ranking but the reward never lands. This is why the fallback below is worth having.

If Votifier is not an option

Some setups simply cannot expose a second TCP port: managed hosts with a hard port limit, servers behind a proxy that only forwards the game port, and every non-Minecraft game.

Two alternatives, both on your listing's settings:

HTTP postback. Give us a URL and we POST a JSON payload to it on every vote. Your web server, not your game server, receives it — which usually solves the port problem outright, since port 443 is already open. Deliveries are signed, retried with backoff, and logged on your listing page so you can see exactly what we sent and what came back.

Incentive check API. Instead of us pushing to you, your server asks us. Call GET /api/v1/incentive?username=... with your listing API key and we tell you whether that player has an unclaimed vote. Mark it claimed when you hand out the reward. This is the most robust option — it survives your server being offline, since the vote is simply waiting there when it comes back — and it is what most RSPS and custom emulators end up using.

Full request and response shapes are in the API documentation.

Worth doing properly

Vote rewards are the difference between a couple of dozen votes a month and a couple of thousand. Given that ranking is votes and nothing else, the hour you spend getting Votifier working is probably the highest-value hour you will spend on your listing.

If you have worked through the list above and it still does not fire, send us the output of nc -vz and your listing URL through the contact form under the API topic, and we will look at what our end is seeing.