Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · Discord

Discord Module troubleshooting#

Use the symptom that matches what actually failed. The integration has several stages—Discord registration, Minecraft client association, clan authentication and channel linking—so “Discord does not work” can represent very different problems.

/register-client works, but /discord_register client <id> fails#

Check these in order:

1. Use the Discord user ID shown by /register-client.
2. Confirm the Discord registration is still pending/active and was created by the intended Discord account.
3. Confirm the Minecraft command is exactly /discord_register client <discord_id>.
4. Confirm the player has uclans.discord_register.admin.
5. The current handler also requires the player to belong to a clan and pass the configured Discord-Edit clan-role permission.
6. Check the first integration connection error in the Minecraft console/message flow.

The integration service can reject an association if the Discord account or Minecraft client identity is already linked somewhere else.

/clan discord register says the client is not registered#

The clan cannot authenticate until the client-association step is complete.

Run the flow again in this order:

Discord:    /register-client
Minecraft:  /discord_register client <discord_id>
Minecraft:  /clan discord register
Discord:    /link

Do not skip directly to /link.

/clan discord register says the clan role cannot do this#

This is normally the UltimateClans internal role permission, not the Bukkit permission.

Check:

Config.Permissions.edit.name

Default:

Discord-Edit

The default applicable roles are moderator and admin. If you customized clan roles or permission values, confirm the member actually receives Discord-Edit=true.

Minecraft gives a token, but Discord /link fails#

Possible causes include:

• invalid/mistyped clan UUID/token;
• client registration is missing;
• the clan token belongs to another registered client;
• the Discord channel is already linked;
• the clan is outside the current plan allowance;
• the integration service cannot currently match the authenticated clan connection.

Use /unlink first if the Discord channel already has a link.

Clan reached the free limit#

The supplied integration service allows up to 5 clans for a registered client without the active TribeSync Webhook subscription. Additional clan authorization can be rejected/suspended.

The module intentionally treats plan suspension differently from a permanent deregistration: it preserves the saved clan state and uses a slower recovery/reconnect path. After the client becomes eligible again, allow time for reconnection or run the normal clan registration flow to verify state.

CHAT works Minecraft → Discord, but Discord → Minecraft fails#

Check:

1. The Discord channel was linked as CHAT, not NOTIFICATION.
2. The clan's Minecraft connection is currently online/authenticated.
3. Send plain text only.
4. Do not include URLs, backticks/code blocks or attachments.
5. Keep the test message short.
6. Wait for the bridge cooldown before sending another message.

If Minecraft is offline/disconnected, the supplied Discord integration removes the attempted Discord message and posts a temporary send-failed notice rather than queuing it.

Minecraft global chat does not appear in Discord#

This is expected. The module forwards UltimateClans clan chat, not every server message. Test while the player is actually using the clan chat context.

Messages in the NOTIFICATION channel disappear#

This is expected behavior. NOTIFICATION is a Minecraft → Discord channel. User messages typed there are removed and are not forwarded to Minecraft.

Use a separate channel linked as CHAT for conversation.

Incoming Discord message formatting looks wrong#

Check:

Config.Discord.message_format

Supported fields are:

{player} {message} {role} {server} {uuid}

If a field remains literal, verify spelling/case and make sure the YAML value still contains valid MiniMessage formatting.

Clan was connected before restart but is now offline#

The module attempts to restore clans saved with Discord state CONNECTED when the UltimateClans plugin lifecycle starts. If a clan does not reconnect:

• check the client association is still valid;
• confirm the integration service is reachable;
• check whether the clan is suspended by plan allowance;
• look for an authorization/connection close reason before deleting any saved state.

Normal disconnects use progressive retry delays, so repeated manual register/unregister operations can make diagnosis harder.

Client was deregistered#

When the integration service reports a client deregistration, the module treats it as an authorization failure, marks the clan Discord state disconnected and removes the active clan connection.

Run /register-client and /discord_register client <discord_id> again only after confirming that deregistration was intentional.

Discord channel was deleted#

The companion integration listens for channel deletion and removes stale channel linkage. Recreate the Discord channel, then run /link again with the clan token.

Discord messages are blocked#

The Discord → Minecraft bridge intentionally rejects:

• links;
• inline/block code formatting;
• attachments.

Long messages are shortened to approximately 200 characters. There is also a short message cooldown.

These restrictions are bridge behavior, not an UltimateClans chat-formatting bug.

What to include in a support ticket#

Provide:

• UltimateClans version and Discord Module version;
• which step failed: /register-client, /discord_register, /clan discord register, /link, CHAT or NOTIFICATION;
• whether the clan is within the current client allowance;
• the first relevant Minecraft console/error message;
• whether the problem survives a server restart;
• whether another clan on the same registered client works.

Do not post integration tokens, private client identifiers, bot tokens, database credentials or other secrets publicly.