# Troubleshooting ## Troubleshooting & FAQ Common issues, in roughly the order they tend to come up. ### Plugin doesn't load #### "TrialChamberPro not loaded — cannot activate TCP-VaultCrates." You're missing the free TCP plugin. [Get it on Modrinth](https://modrinth.com/plugin/trialchamberpro). Min version: v1.4.0. #### "License verification FAILED." Your JAR's embedded license key isn't valid. Look at the `reason` string in the failure log — it disambiguates the cause: * **`fingerprint_revoked`** — *you (or an admin)* revoked this specific server from your dashboard at `https://esmp.fun/plugins/dashboard.php`. The licence is still valid on your other servers; if this revocation was a mistake, email `support@esmp.fun` to have the fingerprint restored. * **`revoked`** — the entire licence was revoked (refund, chargeback, or redistribution detection). Contact `support@esmp.fun`. * **`on_hold`** — the licence has been placed on hold pending resolution of an issue (typically: we contacted you about the same key being seen on multiple servers and didn't hear back). Reply to the email we sent you and we'll release the hold. * **`unknown_key`** — the licence key embedded in your JAR is not recognised by our database. The JAR was probably downloaded by someone else and copied to your server. License keys are tied to your buyer account on Voxel/esmp — re-download under your own account. * No `reason` / network error — the marketplace API is genuinely down. The plugin's 3-day offline grace cache should kick in for legitimate buyers; if it doesn't, wait a few minutes and restart. #### "License key sourced from config.yml fallback." You're running a JAR whose embedded license placeholder (`%%__LICENSE__%%`) wasn't substituted by the marketplace's CDN. This means either: * You built the JAR yourself locally (legitimate dev build) — this is expected. Set `license.key` in `config.yml` to a working test key. * You acquired the JAR from somewhere other than Voxel/esmp — re-download from the marketplace. The plugin runs in either case (using the config.yml fallback), but the warning surfaces silently-modified JARs. #### `ClassNotFoundException` at startup Almost always means your Paper version is too old. The plugin needs **Paper 1.21.7+** for the Dialog API used by the admin GUI (added MC 1.21.6, Paper bindings since 1.21.7) plus the `Vault.addRewardedPlayer` family for the open flow. Update your server. If the missing class is in `io.papermc.paper.dialog.*` or `io.papermc.paper.registry.data.dialog.*` you're definitely on an older Paper than 1.21.7 — those packages didn't exist before then. If you're already on Paper 1.21.7+ and still seeing this, paste the full stack trace into Discord — there are edge cases on certain Paper forks. ### Plugin loads but commands don't work #### `/tcpvc gui` does nothing / I get "Unknown command" Two things to check: 1. Console at startup — do you see the `╔══ TCP-VaultCrates v1.0.0 ══╗` banner? If not, the plugin failed to enable. Scroll up for ERROR lines. 2. `/plugins` — is TCP-VaultCrates in the list, in green? Red means it failed to enable; orange means it's disabled. #### "You don't have permission to use this command" You don't have `tcpvc.admin`. Op yourself (or grant the permission via your perms plugin). For temporary testing as op: ``` /op YourName ``` #### Tab-completion doesn't work / shows nothing Tab-completion is per-permission. If you don't have `tcpvc.admin`, tab-completion for admin commands hides the matches. Op yourself to verify it's a permission issue, not a plugin bug. ### Vaults #### "That block isn't a Vault." but it clearly is a vault Vault blocks come in two material types: `VAULT` and... no, actually they share one Bukkit `Material.VAULT`. The ominous variant is a BlockData flag, not a separate material. If `/tcpvc set` rejects a clearly-vault block, it's almost always because: 1. You're not actually looking at it (Minecraft's hitbox detection is sometimes off — try moving 1 step closer). 2. The block range is 8 blocks; you're standing too far away. 3. The block was placed by another plugin that replaces vault blocks with something custom. Run `/data get block ~ ~ ~` while standing on it to confirm it's actually a `minecraft:vault`. #### Vault opens for player A but won't open for player B Per-player tracking is **vanilla** — Paper stores the rewarded-players list in the block's NBT. Each player has independent open state. Player B's vault is fine; if B already opened it, B sees "already opened" until the cooldown expires. If you want to verify B's state, check the vault block's data: ``` /data get block ~ ~ ~ Block.RewardedPlayers ``` (Stand on the vault first.) #### Hologram disappeared after server restart TextDisplay holograms are non-persistent — they vanish on server shutdown and respawn when the chunk loads. The plugin's reconcile loop (every 1 second) recreates them automatically. If you see no hologram a few seconds after a chunk is loaded: 1. Confirm the vault is still registered: `/tcpvc list` should include it. 2. If it's missing from the list, the chunk didn't reload our PDC correctly. This is rare; restart the server to force a full chunk re-scan. ### Keys #### Key item doesn't open the vault The plugin matches keys by their **PDC tags**, not their visible appearance. If you've somehow created a regular Amethyst Shard with the same display name as the Common Key, it still won't work — the PDC tags are missing. Verify the key is real: 1. Hold the key in your main hand. 2. Run `/data get entity @s SelectedItem` and look for a `tcpvc:crate_id` and `tcpvc:key_tier` entry in the components. If those are missing, the item is a fake. Get a real one with `/tcpvc key give YourName ...`. #### Players hoarding keys for an event — keys lose their PDC Keys shouldn't lose their PDC tags under normal use. They survive: * Inventory swaps * Chest storage / shulker box storage * Anvil renames * Trading between players (if your server allows) They **don't** survive being recreated from raw NBT (`/give @s amethyst_shard{display:{Name:'...'}}`) — those are new items, not copies of keys. The PDC tags can only be set by the plugin's own `buildKey` path. #### Keys don't stack Keys of the same crate + tier always stack. Keys of different crates (or different tiers of the same crate) won't stack — they have different PDC tags and Bukkit treats them as different items. ### Drops #### Players are losing dropped loot to other players The owner-lock window must have expired. Check `config.yml`: ```yaml crates: drop-on-full-inventory: enabled: true owner-grace-seconds: 30 ``` Bump `owner-grace-seconds` higher (e.g. `120` for 2 minutes), or set to `0` to make drops owner-only until they despawn (5 minutes vanilla). Also check that no player has `tcpvc.bypass.droplock` who shouldn't — it's `default: op`, so non-op accounts shouldn't have it unless explicitly granted. #### Items vanishing immediately when dropped Either ClearLag or a similar plugin is removing them. ClearLag respects the `Item.owner` tag in its newer versions, but you may need to add a whitelist exception explicitly. Check ClearLag's config for an "owned-items" section. ### Holograms #### Holograms float in the wrong place Tweak `holograms.y-offset` in `config.yml`. Default `1.5`. Negative values place the text below the vault. #### Hologram lines don't render correctly (showing `` literally) Your `messages.yml` (or `crates.yml` `display-name`) has a typo — unclosed `` tag, mismatched bracket, etc. Open the file and look for the obvious culprit. The console doesn't validate MiniMessage at parse time; broken tags render as literal text. ### YAML errors #### "could not be parsed correctly: expected ''" Almost always a tab character somewhere in the file. YAML requires spaces, not tabs, for indentation. Open the file in an editor that shows whitespace and convert all tabs to spaces. #### "no presets loaded" / "no crates loaded" The whole file failed to parse. Check the line number in the error (if any), and the most common culprits: * Tabs (see above). * Unbalanced quotes (`"some text` without a closing `"`). * Indentation jumps (a child key indented less than its parent). Restore from `crates.yml.bak` if you have one, or delete the file entirely to regenerate the bundled defaults. ### When to ask for help If none of the above applies, hop into the Discord linked from the marketplace product page. Include: * Plugin version (`/tcpvc help` shows it). * Server software + version (`Paper 1.21.7`, `Folia 1.21.8`, etc.). * The full console log around the moment the issue happened, or a pastebin link to it. * The relevant config block from `config.yml` / `crates.yml` / `messages.yml`. Tickets with that triple get answered fastest. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://darkstarworks.gitbook.io/plugins/mc/tcp-documentation/tcp-vaultcrates/troubleshooting.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.