Skip to content

Troubleshooting

Aridro Chatterjee edited this page Nov 15, 2026 · 1 revision

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.


1. MineBridge Is Not Loading

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:

  1. Make sure the MineBridge JAR is inside the plugins directory.
  2. Verify that you are using the correct plugin release.
  3. Check your Java runtime version.
  4. Restart your Minecraft server.
  5. Check the server console for loading errors.

You can check loaded plugins using:

/plugins

2. Discord Bot Is Not Connecting

If MineBridge cannot connect to Discord:

Possible Causes:

  • Invalid bot token.
  • Missing bot permissions.
  • Internet connectivity problems.
  • Incorrect Discord configuration.

Solutions:

  1. Verify your Discord bot token.
  2. Make sure the bot application is configured correctly.
  3. Check your server's internet connectivity.
  4. Verify that the bot has access to the configured Discord server.
  5. 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.


3. Discord Messages Are Not Appearing

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: true

Also verify the relevant event-specific settings in config.yml.


4. Minecraft Chat Relay Is Not Working

If messages are not being synchronized between Minecraft and Discord:

Check the following:

  1. Make sure chat-relay is enabled.
  2. Verify the Discord bot connection.
  3. Check the configured Discord channel.
  4. Verify that the bot has permission to read and send messages.
  5. Check the server console for errors.

Configuration:

features:
  chat-relay: true

5. Player Join and Leave Notifications Are Missing

If 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: true

Make sure the relevant settings are enabled.


6. Death Notifications Are Not Working

If death notifications are missing:

Check the main death message settings:

death-messages:
  enabled: true

  minecraft:
    enabled: true
    broadcast: true

  discord:
    enabled: true
    embed: true

Also 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: true

Make sure the relevant category is enabled.


7. Advancement Notifications Are Missing

If advancement or challenge notifications are not appearing:

Check the following configuration:

achievements:
  enabled: true

  minecraft:
    enabled: true

  discord:
    enabled: true

  challenges:
    enabled: true

Also verify that the relevant advancement categories are enabled.


8. Discord Embeds Are Not Appearing

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: true

Verify that the bot has permission to embed links and send messages in the configured channel.


9. Configuration Problems

Incorrect YAML formatting can cause configuration problems.

Common mistakes:

  • Incorrect indentation.
  • Missing quotation marks.
  • Incorrect configuration values.
  • Invalid channel IDs.
  • Incorrectly formatted placeholders.

Recommendations:

  1. Use spaces instead of tabs.
  2. Preserve the original YAML structure.
  3. Check indentation carefully.
  4. Compare your configuration with the default config.yml.
  5. Check the server console after startup.

10. Still Having Problems?

If none of the solutions above resolve your issue, consider opening a GitHub issue.

When reporting a problem, include:

  1. MineBridge version.
  2. Minecraft server version.
  3. Server software (Paper, Purpur, Spigot).
  4. Java version.
  5. Relevant server console logs.
  6. Steps to reproduce the problem.

Report Issues:

MineBridge GitHub Issues


Related Documentation


MineBridge — Connecting Minecraft communities with Discord.

Clone this wiki locally