Troubleshooting

Troubleshooting

Start by confirming that the server is actually running BlueMapWebChat 4.6.1. For cross-server DM problems, verify every participating server is running 4.6.1 and has matching relay configuration.

Web page or API does not open

Check:

• enabled: true
• http.host / http.port
• Port 8899 conflicts
• Firewall rules
• Reverse-proxy upstream/path
• standalone-web.enabled: true when testing /chat

Behind a local HTTPS proxy, verify BMChat is actually listening on 127.0.0.1:8899.

BlueMap chat panel is missing

Check:

• web-addon.auto-install: true
• web-addon.auto-patch-webapp-conf: true
• BlueMap web root/webapp config paths
• Addon install/patch messages in the server log
• /bluemap reload
• Browser hard refresh/cache

Web chat does not reach Minecraft

Check chat.send-web-chat-to-game and any other chat-format/bridge plugin that may replace or cancel output. For remote messages, also check server-relay.delivery.game.

Minecraft chat does not appear on the web

Check chat.broadcast-ingame-chat-to-web and whether another plugin cancels or exclusively handles the final chat event.

Reply click does not work

Check the reply.game-click settings. URL fragments intentionally keep OPEN_URL behavior rather than being replaced by a reply action.

Remote DM goes to a local same-name/same-UUID player

BlueMapWebChat 4.6.1 routes remote recipients by server ID + UUID.

1. Verify every participating server is running BlueMapWebChat 4.6.1.
2. Verify each server-relay.server-id is unique.
3. Verify the clicked message carries the correct origin server ID.
4. Hard-refresh the browser after replacing web assets.

DM session appears only on the sending server

Check the receiving server and relay configuration first.

• Verify all participating servers are running BlueMapWebChat 4.6.1.
• Fully restart servers after updating the plugin.
• Check peer IDs, peer URL, and shared secret.
• Check the receiving server log for relay authentication or routing errors.

Remote DM name contains duplicate tags such as [Main] [server1]

BlueMapWebChat 4.6.1 keeps the routing ID and friendly server name separate. If duplicate labels remain:

• Confirm every participating server runs BlueMapWebChat 4.6.1.
• Restart after JAR replacement.
• Hard-refresh browser assets.

Remote DM dialog does not show the server until after sending

BlueMapWebChat 4.6.1 labels a remote recipient immediately in the DM dialog, e.g. [Main] PlayerName. If not:

• Verify the current JAR was loaded after a restart.
• Run /bluemap reload if needed.
• Hard-refresh the browser.

Server relay: 403 unknown_peer

The receiving server must have an enabled peer whose id exactly matches the sender's server-id.

Server relay: 401 bad_signature

Check effective secrets on both ends, request body/header preservation by the proxy, and whether a per-peer secret overrides the shared secret.

Server relay: 401 expired_request

System clocks differ by more than max-clock-skew-seconds. Fix NTP/time synchronization.

Login problems

Check link-code expiry, password-login settings, brute-force lock state, cookie/domain/HTTPS behavior, and admin source-IP restrictions.

Client IP is always the proxy address

Configure http.trusted-proxies for the actual proxy IP/CIDR. Do not broadly trust Internet sources.

Emoji token appears as text

Web side:

• Check emoji.enabled and the BlueMapWebChat emoji file path.

Minecraft side:

• Check ImageEmojis-Bero, current resource pack, permissions, and /emojis reload / /emojis update.
• For remote relay, synchronize the same pack/name files to receiving servers.

Picker-specific issues: ImageEmojis Client Picker.

Upload fails

Check role permissions, extension allowlist, file/total size limits, per-minute limit, filesystem write permission, and reverse-proxy forwarding of the upload path.

Web Push fails

Check HTTPS, browser notification permission, Service Worker/Push API support, VAPID configuration, and on iOS/iPadOS the Home Screen-installed PWA requirement.

Update notice does not appear

Check:

update-check:
  enabled: true

Also verify Modrinth is reachable and the player has bluemapwebchat.update.notify (OP by default).

Configuration change seems ignored

• Config only: /bmchat reload
• JAR replacement: server restart
• BlueMap web assets: /bluemap reload
• Browser JS/CSS: hard refresh

Useful information for a bug report

Provide:

• Exact BlueMapWebChat JAR/checksum
• Relevant config blocks with secrets/passwords removed
• logs/latest.log around the failure
• Logs from both servers for relay/DM issues
• HTTP status code for relay/API failures
• Browser Console/Network errors for web UI issues
• Loader/Minecraft/client-mod versions for ImageEmojis Picker issues