FAQ and Troubleshooting

Setup

What is ProVouchers, in one sentence?

A plugin that turns rewards into items players hold (vouchers) or words they type (codes), defined in YAML, with anti-dupe protection and a typed reward and condition system.

Does ProVouchers need any other plugin?

No. ProVouchers is fully self-contained; integrations (Vault, LuckPerms, custom items, and so on) are optional and detected automatically when installed. Versions before 1.0.0 required the Strata library plugin; that requirement is gone.

It says it disabled on startup. Why?

A clean disable means the server is not on Java 25 / Paper 26.1+. The console line says exactly that.

Does it work on Folia?

Yes. ProVouchers is Folia-safe throughout: redemption checks run on the player's region thread, database work runs asynchronously, and rewards are scheduled back on the player.

I see a `sun.misc.Unsafe` warning at startup. Is something wrong?

No, and it is not from ProVouchers. A line like WARNING: sun.misc.Unsafe::objectFieldOffset has been called by org.joml.MemUtil comes from JOML, a math library the server itself ships in its own libraries/ folder, not from any plugin. It is a harmless one-time JDK deprecation notice on Java 24+, and the server runs normally; it goes away once your server software bundles an updated JOML. To silence it, add --sun-misc-unsafe-memory-access=allow to your JVM arguments, before -jar.

Configuration

Where do I configure a voucher?

In plugins/ProVouchers/vouchers/<name>.yml, one voucher per file. Codes live in plugins/ProVouchers/codes/. Server-wide settings (database, anti-dupe, metrics) live in plugins/ProVouchers/config.yml. See Core Concepts.

How do I apply changes without restarting?

Run /voucher reload. It reloads every voucher and code file and reports mistakes per file. Changes to config.yml (storage, metrics) need a server restart.

`/voucher reload` printed an error. How do I read it?

The format is file.yml: <where> <reason>, for example crate_key.yml: voucher 'crate_key': item.material unknown material 'DIMAOND'. Fix the named key and reload again. The other files still load while one is broken.

Can I use `&` colour codes?

No. ProVouchers uses MiniMessage (<gold>, <gradient:...>, <#FF8800>). See Text and Placeholders. Legacy & codes are not parsed.

My permission condition does nothing.

The key is permission:, not value::

conditions:
  - type: permission
    permission: "provouchers.use.example"   # correct

Each condition type has its own key (world uses worlds, exp uses level). See Conditions.

Items and textures

My custom item shows up as plain paper.

custom: "itemsadder:..." is resolved through an item hook (ItemsAdder, Oraxen, Nexo, Head Database), so the usual causes are: the provider plugin is not installed, or the item id is wrong. When the reference cannot be resolved, the voucher falls back to its material (default PAPER). See Items. Vanilla custom-model-data separately needs a resource pack to show.

How do I give an item with a custom texture?

Two ways: set custom-model-data if you serve a resource pack that defines the model, or reference a provider item with custom: "itemsadder:..." (ItemsAdder, Oraxen, Nexo). See Items.

How do I test custom model data without making a texture?

Ship a tiny resource pack that remaps a vanilla item to a different vanilla model by number. Then a PAPER with that custom-model-data renders as, say, a diamond. This confirms the wiring without any art.

Not as individual keys yet. Use a provider item (ItemsAdder, Oraxen, Nexo) that already encodes the full item, or give the item through a command: reward.

Rewards and economy

A reward did not run, but the others did.

Rewards run independently. A reward that fails (a command that errors, a provider item that is not installed, no economy plugin) is logged to the console against its voucher and skipped, so the rest still run. Check the console for a line naming the reward and the reason. See Rewards.

My `currency` reward did nothing.

currency needs a Vault-compatible economy installed. With no economy provider, the reward is skipped and logged. Install Vault and an economy plugin. See Integrations.

How do I charge a player to redeem a voucher?

Check their balance with an economy condition, and deduct with a currency: take reward:

conditions:
  - type: economy
    amount: 500
    deny: "<red>You need $500."
rewards:
  - "currency: take 500"
  - "item: DIAMOND 1"

How do I give a different reward each time?

Use random-rewards with weighted sets; one is chosen per redeem. See Random rewards.

Can a voucher run another plugin's command?

Yes. Use a command: reward (console) or player-command: (as the player):

rewards:
  - "command: crates give %player% vote 1"

Limits and expiry

My voucher expired the moment I gave it.

You probably put a relative duration on a code (expiry: "30d"). Codes have no per-item give time, so use an absolute ISO instant for code expiry (2026-12-31T23:59:59Z). On voucher items, 30d works and is measured from the give time. See Voucher expiry.

Do cooldowns survive a restart?

Yes. Cooldowns are persisted to the database and reloaded when a player joins. On a network sharing one database, a voucher's cooldown applies across all servers. See the Voucher Reference.

How do I limit a code to the first N players?

Set max-uses on the code. Set uses-per-player for a per-player cap. Both survive restarts. See Code Reference.

How do I make a voucher only the recipient can redeem?

Set owner-only: true. The recipient's identity is stamped when the voucher is given, and other players are rejected. See Flags.

How do I make a display-only item that cannot be redeemed?

Set unredeemable: true. It looks like a voucher but does nothing when right-clicked, useful for collectibles or showcases.

Anti-dupe and security

Can players duplicate vouchers?

An anti-dupe voucher (stackable: false) stamps each item with a unique id, so a copied item shares that id and is rejected as a duplicate on redeem. Stackable vouchers (the default) are not dupe-tracked. Creative redemption is blocked by default and item frames are denied. See Anti-Dupe.

Why can't I redeem a voucher in creative?

Creative and spectator are blocked by default, because creative makes item cloning trivial. Grant provouchers.bypass.gamemode to allow it.

How do I get alerts when someone tries to dupe?

Grant provouchers.notify to your staff. They receive a chat alert naming the player and the voucher.

Commands and giving

Can I give a voucher to an offline player?

Yes, as a virtual voucher in their Stash. /voucher give and giveall hand over a physical item, so they reach online players only, but /voucher stashgive <player> <id> [amount] [argument] queues the voucher for any player who has joined the server before, online or not. They claim it from /stash next time they play. The API equivalent is VoucherService.stash(uuid, id, amount).