FAQ & troubleshooting

FAQ#

How do players link their accounts?

Run /connect in Minecraft to get a one-time code, then send that code to the bot in Discord (or use /connect <code>). /disconnect unlinks. See Account linking.

Does it work on a BungeeCord or Velocity network?

Yes. Install it on the proxy alone for the simplest setup, or on the proxy plus each Spigot backend (with proxyMode: true) to relay Spigot-only extras. See Proxy & networks.

Do I need MySQL?

No — SQLite is built in and needs zero setup. Use MySQL/MariaDB only when you want a shared store across a network. See Database.

Can I sync multiple roles and groups?

Yes — add as many group and permission mappings as you like, each with its own authority. See Role & permission sync.

The bot won't connect#

• Double-check bot.token in config.yml — no quotes issues, no trailing spaces.
• Enable the Server Members and Message Content intents in the Developer Portal.
• Read the server console on startup — JDA logs the exact login failure.
• Reset the token in the portal if it may have leaked, and paste the new one.

Chat isn't syncing#

• Confirm channels.chatSync holds the right channel ID (Developer Mode → Copy ID).
• Make sure the bot can read and send in that channel, and has Manage Webhooks for WEBHOOK type.
• Check no one has discordsynthesis.bypass.chatsync.
• If you use a chat plugin, review usePrefix / useChannels and custom chat hooks.

Roles aren't syncing#

• Install LuckPerms — group and permission sync read from it.
• Verify each mapping's role ID is correct.
• Move the bot's role above the roles it manages in Discord's role list.
• Confirm the Server Members intent is on, and re-check the mapping's authority.

Database connection issues#

• Create the database/schema before starting — the plugin won't create it for you.
• Verify host, port, username, and password in config.yml.
• Grant the user full rights on that schema.
• On a network, every server and the proxy must point at the same database.