Troubleshooting

Troubleshooting

BlueMapWebChat 4.7.0 · Minecraft 1.18–26.2 · Java 17 baseline

35. Troubleshooting Quick Reference

Page Does Not Open

• Confirm enabled: true
• Check http.host and http.port
• Check for a port conflict
• Confirm reverse-proxy upstream points to 127.0.0.1:8899
• Enable standalone-web.enabled when a standalone page is required

No BlueMap Chat Button

• Enable web-addon.auto-install
• Enable web-addon.auto-patch-webapp-conf
• Check BlueMap paths
• Read installation/patch log messages
• Run /bluemap reload
• Refresh browser cache

Login Fails

• Check HTTPS domain and cookie path
• Confirm link code expiration
• Check login lockout logs
• Verify auth.password-login
• Check administrator IP restrictions

Web Chat Does Not Reach Game

• Set chat.send-web-chat-to-game: true
• Confirm players are online
• Check chat-format plugin conflicts
• For relay messages, confirm server-relay.delivery.game: true

Game Chat Does Not Reach Web

• Set chat.broadcast-ingame-chat-to-web: true
• Check player permissions and event cancellation
• Check whether another chat plugin exclusively consumes the event

Reply Click Does Not Work

• Enable reply.game-click.enabled
• For local game messages, enable local-game-chat
• Check chat-format plugin conflicts
• URL parts opening a link instead of replying is expected

Emoji Token Is Shown as Text

• Confirm the BMChat emoji file exists
• Check ImageEmojis-Bero shared folder and permission
• Enable replaceInCommands
• Run /emojis reload and /emojis update
• Confirm matching emoji files on every relay server

Relay Returns 403

• Compare receiver peers[].id with sender server-id
• Reload the receiving server too
• Check the active-peer log

Relay Returns 401

• Compare the actual effective secrets
• Confirm the proxy does not modify body or HMAC headers
• Check server clock synchronization

Discord Prefixes Are Duplicated

• Confirm every server runs the same fixed build
• Check for another plugin reposting relay messages
• Keep game-to-discord: false when DiscordSRV already forwards game chat

Web Push Does Not Work

• Confirm HTTPS
• Check notification permission
• Check Service Worker and Push API support
• On iOS, use an installed Home Screen web app
• Check VAPID subject and key files

Installation troubleshooting reference

Requirements

• Bukkit/Spigot/Paper-compatible server or compatible fork
• Java 17 or newer for build/runtime
• BlueMap plugin and a working BlueMap webroot
• The chat API port must be reachable by the browser. Default: 8899/tcp
• DiscordSRV is optional and only needed when enabling the Discord bridge

Build

mvn clean package

Output:

target/BlueMapWebChat-4.7.0.jar

Install or upgrade

1. Stop the Minecraft server.
2. Replace the old BlueMapWebChat jar in plugins/ with the new jar.
3. Start the server.
4. Check plugins/BlueMapWebChat/config.yml.
5. Run /bmchat reload or restart if you changed important paths.
6. Run /bluemap reload if BlueMap does not pick up webapp changes automatically.
7. Hard-refresh the browser.

Verify web addon registration

grep -R "bluemap-web-chat" -n /opt/minecraft/server/plugins/BlueMap/webapp.conf

The entries should include the current version query, for example:

addons/bluemap-web-chat/config.js?v=4.7.0-<cache-token>
addons/bluemap-web-chat/chat.js?v=4.7.0-<cache-token>
addons/bluemap-web-chat/chat.css?v=4.7.0-<cache-token>

Also verify the actual web files were updated:

find /opt/minecraft/server -path "*addons/bluemap-web-chat/chat.js" -printf "%p  %TY-%Tm-%Td %TH:%TM\n"

BlueMap webroot mismatch

If /api/config works but the chat panel does not appear, BlueMap may be serving a different webroot than the one configured in BlueMapWebChat.

Check BlueMap's webapp.conf and make sure these match your setup:

web-addon:
  bluemap-web-root: "bluemap/web"
  bluemap-webapp-conf: "plugins/BlueMap/webapp.conf"
  addon-path: "addons/bluemap-web-chat"

Browser cache

When testing web UI changes, open DevTools, enable Network -> Disable cache, then hard-refresh the page.

You can also check the loaded version in the console:

[...document.scripts]
  .filter(s => s.src.includes("bluemap-web-chat"))
  .map(s => s.src)

BlueMap still loads an older addon version

If BlueMap still loads an older BlueMapWebChat addon version after updating, run /bmchat reload once more or restart the server, then hard-refresh the browser.

HTTPS reverse proxy

For public servers, use HTTPS through Caddy or nginx. See:

• docs/CADDY_HTTPS_EN.md and examples/caddy/Caddyfile
• docs/NGINX_HTTPS_EN.md and examples/nginx/bluemapwebchat.conf