Repository navigation
Troubleshooting
This guide covers common issues that administrators may encounter while installing, configuring, and running MineBridge.
If you experience problems with MineBridge, follow the troubleshooting steps below.
If MineBridge does not appear in your server's plugin list:
Possible Causes:
- Incorrect plugin JAR file.
- Unsupported Java runtime.
- Incompatible server software.
- Plugin loading errors.
Solutions:
- Make sure the MineBridge JAR is inside the
pluginsdirectory. - Verify that you are using the correct plugin release.
- Check your Java runtime version.
- Restart your Minecraft server.
- Check the server console for loading errors.
You can check loaded plugins using:
/plugins
If MineBridge cannot connect to Discord:
Possible Causes:
- Invalid bot token.
- Missing bot permissions.
- Internet connectivity problems.
- Incorrect Discord configuration.
Solutions:
- Verify your Discord bot token.
- Make sure the bot application is configured correctly.
- Check your server's internet connectivity.
- Verify that the bot has access to the configured Discord server.
- Check the server console for connection errors.
Security Reminder: Never share your Discord bot token publicly.
MineBridge supports the MINEBRIDGE_BOT_TOKEN environment variable for securely providing the bot token.
If Minecraft events or messages are not appearing in Discord:
Check the following:
- Is the Discord bot connected?
- Is the configured channel ID correct?
- Does the bot have permission to send messages?
- Are the relevant features enabled?
- Are the Discord event settings enabled?
Example configuration:
discord:
channel-id: ""
features:
chat-relay: true
join-leave-notifications: trueAlso verify the relevant event-specific settings in config.yml.
If messages are not being synchronized between Minecraft and Discord:
Check the following:
- Make sure
chat-relayis enabled. - Verify the Discord bot connection.
- Check the configured Discord channel.
- Verify that the bot has permission to read and send messages.
- Check the server console for errors.
Configuration:
features:
chat-relay: trueIf player activity notifications are not appearing:
Check these settings:
features:
join-leave-notifications: true
discord-events:
enabled: true
player-events:
enabled: true
join: true
leave: true
first-join: trueMake sure the relevant settings are enabled.
If death notifications are missing:
Check the main death message settings:
death-messages:
enabled: true
minecraft:
enabled: true
broadcast: true
discord:
enabled: true
embed: trueAlso verify the individual death categories.
For example:
categories:
player-kill: true
mob-kill: true
fall: true
lava: true
fire: true
drowning: true
void: true
explosion: true
environmental: true
other: trueMake sure the relevant category is enabled.
If advancement or challenge notifications are not appearing:
Check the following configuration:
achievements:
enabled: true
minecraft:
enabled: true
discord:
enabled: true
challenges:
enabled: trueAlso verify that the relevant advancement categories are enabled.
If notifications are being delivered without the expected embed formatting:
Check:
discord-events:
enabled: true
embeds:
enabled: true
footer: "MineBridge | Minecraft Events"For death notifications, also check:
death-messages:
discord:
embed: trueVerify that the bot has permission to embed links and send messages in the configured channel.
Incorrect YAML formatting can cause configuration problems.
Common mistakes:
- Incorrect indentation.
- Missing quotation marks.
- Incorrect configuration values.
- Invalid channel IDs.
- Incorrectly formatted placeholders.
Recommendations:
- Use spaces instead of tabs.
- Preserve the original YAML structure.
- Check indentation carefully.
- Compare your configuration with the default
config.yml. - Check the server console after startup.
If none of the solutions above resolve your issue, consider opening a GitHub issue.
When reporting a problem, include:
- MineBridge version.
- Minecraft server version.
- Server software (Paper, Purpur, Spigot).
- Java version.
- Relevant server console logs.
- Steps to reproduce the problem.
Report Issues:
MineBridge — Connecting Minecraft communities with Discord.
Getting Started
Documentation
Support
Developers
[GitHub Repository](https://github.com/aridrochatterjee/Minebridge)
[Modrinth Page](https://modrinth.com/plugin/minebridge)