Troubleshooting

If your Minecraft server doesn't show as Connected in the dashboard:

• Check that the Madsi JAR is in the right folder (mods/ on Fabric / NeoForge, plugins/ on Paper / Purpur) and the server has been restarted
• Verify that config/madsi.json has the correct token
• Confirm your server runs a supported version: Minecraft 1.21.9-26.3 on Fabric, Paper/Purpur, or NeoForge
• Make sure the right Java is installed: 21 for 1.21.9-1.21.11, 25+ for 26.1-26.3
• Check that your firewall isn't blocking outbound WebSocket connections
• Try regenerating the token from the server's Settings page (Server → Settings)

If /link isn't working:

• Make sure you're signing in with the Microsoft account that owns your Minecraft Java Edition
• The link expires after a few minutes: try running /link again for a fresh one
• If you get a Microsoft error, try clearing your browser cookies and signing in again
• The welcome message after linking is a DM: a member whose DMs are closed is still linked, they just don't get it
• Ensure the bot is still in the Discord server and has the correct permissions

If whitelist changes aren't reflected on your Minecraft server:

• Confirm the Minecraft server shows as Connected in the dashboard
• Check that white-list=true is set in server.properties
• Verify you have at least one active whitelist rule
• Check that Madsi manages the whitelist is on in the server's Settings
• Try hitting Refresh in the dashboard sidebar to re-sync metadata
• Check the server console for any Madsi-related errors

If nickname sync isn't working:

• The bot needs the Manage Nicknames permission in Discord
• The bot's role must be higher than the user's highest role in the role hierarchy
• Server owners' nicknames cannot be changed by bots. This is a Discord limitation
• Check that the nickname format is set correctly on the Members page

If the bot doesn't respond to slash commands:

• Check that the bot is still in your server (it may have been kicked)
• Verify the bot has permission to read and send messages in the channel
• Make sure you're using slash commands (type / to see them)
• Check the Madsi status page for any outages

If you get errors during the Microsoft sign-in flow:

• Clear your browser cookies and cache, then try again
• Make sure you're using the correct Microsoft account (the one that owns Minecraft Java Edition)
• Try a different browser or incognito/private window
• If you see "consent required", make sure you're accepting the permissions prompt
• Wait a few minutes and try again. Microsoft auth can have temporary issues