Troubleshooting

License doesn't verify

Symptom: log shows License invalid or expired.

• Check license-key: in settings.yml matches exactly what your dashboard shows. No extra spaces.
• Check your server's outbound IP can reach https://starchat.minestar.me. Behind a firewall? Allow HTTPS to that hostname.
• Already at 3 IPs? Revoke an unused server in your dashboard first.

MiniMessage tags rendering as raw text

Symptom: <gradient:red:gold>VIP</gradient> appears literally.

• You're probably on Spigot. Spigot lacks Adventure's MiniMessage parser by default — install adventure-platform-bukkit or migrate to Paper. Paper, Purpur, and Folia ship Adventure natively.
• On Paper but still raw? Make sure the format part has no &rreset breaking the open tag — MiniMessage and legacy codes don't mix inside the same tag.

Filter blocks something it shouldn't

Symptom: legitimate words match a regex.

• Add the word to filter/filter-whitelist.yml — it short-circuits before any rule fires.
• Disable aggressive mode (use-aggressive-regexes: false) if the false positives are leet-speak adjacent.
• Remove the offending entry from filter-rules.yml entirely.

Mentions don't fire

• The mentioning player needs starchat.mention.use.
• The mentioned player has /chatpingtoggled off — that opt-out beats the sender's permission.
• Mentions only fire on exact name match. Set fuzzy-mentions: true if you want partial-match autocomplete (coming soon — currently exact only).

DiscordSRV doubles or skips messages

• DiscordSRV needs to be on a recent release (1.27+). Older versions process the chat event after StarChat cancels it.
• For staff chat & DMs, StarChat hides them from DiscordSRV by default. Toggle in settings:

Features:
  discordsrv:
    hide-staffchat: true
    hide-private-msg: true

/chatcolor GUI shows wrong items

Symptom: items appear as gray glass instead of dyes.

• The material: in chat-color.yml must be a valid org.bukkit.Material name. BLUE_DYE works; BLUE_DYE_ITEMdoesn't.
• Materials change between MC versions. SUGAR_CANE_BLOCK becomes SUGAR_CANE in 1.13+. Use the modern names.

Console floods with errors after reload

StarChat reloads almost everything live. The exceptions are license-key and feature toggles in settings.yml — if you change those, full restart.

Folia: tasks throwing IllegalStateException

• You're probably calling a region-bound API from a non-region thread in your own listener. StarChat's API exposes FoliaScheduler.run(Entity, Runnable) — use it for any entity-touching code.
• See the API page for examples.

Performance: TPS drop while many minigames running

• Lower min-playersif you don't need a quorum, but raise interval to space games out.
• Unscramble and type-race are zero-cost; trivia is zero-cost; math regenerates a problem per game (microseconds). The TPS hit you see is almost certainly a different plugin.

When to escalate