Skip to main content Link Menu Expand (external link) Document Search Copy Copied
BlueMap

FAQ

Q: Where can I open my map?

By default, it’s your servers public ip-address (e.g. 123.45.67.8) and the port (8100) like this: http://123.45.67.8:8100/
(Make sure you replace 123.45.67.8 with your server-ip. The same ip that you are using to connect to your minecraft-server!)

Q: I still can’t access the website!

Here is a checklist:

  • Do you get a message saying Webserver started... in your server-console/log? If not, look if there are any errors/warnings and check the configuration again.
  • Make sure you are using http and not https when connecting to the webpage.
  • Is the port (8100 by default, TCP) open and forwarded correctly? Or is your firewall blocking incoming connections on the port? If you don’t know this ask your server-host how you can open a second port for BlueMap!.

Q: I am getting 404 - Not Found when I open the map

Check your core.conf configuration file, did you set accept-download to true?
If yes, check if your webroot settings in webapp.conf and webserver.conf are set to the correct (same) folder.

Q: My map isn’t updating!

BlueMap needs to wait until the server saves the world data to disk, so it may take some time for changes to appear on the map. Also make sure to click Update Map in the menu on the left to make your browser fetch a fresh copy.

Q: I’m experiencing issues after updating to a newer BlueMap version!

Please make sure to read the changelog, as there may be more steps necessary than just swapping out the .jar file. Those steps will be clearly listed on the update page.

Q: I have a black map / a lot of the map is missing!

  • Press the Update Map button in BlueMap’s menu. This updates all tiles from the server and makes sure your browser has not cached anything weird.
  • Use /bluemap to check if BlueMap is rendering something! It might be busy rendering a different map first.
  • Use /bluemap unfreeze <map> to make sure it’s not frozen.
  • Make sure that the world:-setting in your map-config is set to the correct world-folder.
  • Make sure that the dimension:-setting in your map-config is correct.
  • Make sure your BlueMap-version supports the minecraft-version you are trying to render. (You can see that on BlueMap’s official download-page)
  • BlueMap can only render the parts of your world that have already been generated by Minecraft! (E.g., by exploring your world or using a plugin to pre-generate an area of your world.)
  • Use the command /bluemap debug block (in-game). If that is throwing an error, it is likely that you have a mod installed that is not compatible with BlueMap. Check the incompatibilities-list at the bottom. If you don’t have any mod from the list, please report the error here.
  • Have you upgraded your world from an earlier Minecraft-version? Or have you pre-generated your world or generated it with e.g. WorldPainter? Then, chunks that have not been visited by a player might not have their light-data generated yet. BlueMap needs the light data and ignores chunks that don’t have it. So it will only render chunks that have been loaded by a player at least once.
    Here is a dedicated guide to fixing lighting issues in your world: https://bluemap.bluecolored.de/community/FixLighting.html

If nothing else works, you can try to set ignore-missing-light-data: true in your map-config. (And then use /bluemap purge <map> to update your map)
This will ignore potentially missing light data while rendering, with some drawbacks:

  • Cave-rendering will always be enabled in those chunks, because it is using the sun-light data to detect the “caves”
  • Everything in those chunks will be rendered fully lit (sun-light value of 15, looks similar to having night-vision)

Q: My map is only loading in low resolution!

This happens when your webapp can’t load the high-resolution tiles for some reason.
This could be caused by one of these things:

  • You have updated BlueMap, but did not update BlueMap’s webapp properly.
    Try to delete the <webroot>/index.html and reload BlueMap.
  • You disabled the hires tiles in your map config.
    Set enable-hires to true in your map config and purge your map so bluemap re-renders it with the hires tiles enabled.
  • You haven’t set up your external webserver correctly.
    Please make sure you’ve read the External Webservers guide to see how to do that.

If you’re still having issues, please visit #support in our Discord.

Q: I have black/pink-checkered blocks on my map!

Read this: https://bluemap.bluecolored.de/wiki/customization/Mods.html

Q: The map (web-app) has low FPS (lagging)

Make sure you have hardware-acceleration enabled on your browser! Use your favorite search engine to learn how to do this :)

If you have a laptop with two GPU-units, make sure that the high-performance GPU is used for your browser. E.g. Intel/Nvidia sometimes like to use the low-performance GPU for your browser by default, to save energy. You can change this in the Nvidia-Control-Panel.

Q. Chunks (tiles) are loading in really slowly

BlueMap needs to convert your world’s chunks to 3D model files. (We often refer to this process as “rendering”.)
If you have just installed BlueMap, this might take a while, because it is the first time.
You can check the progress with /bluemap. You may just have to wait for the chunks to finish being converted.

Once the 3D model files have been generated, they are stored on your server. They then get requested from people visiting your BlueMap website.
The speed at which those files get transferred from the server to the browser is almost entirely dependent on the network speed between your server and your own computer.
You can debug this by using your browser’s built-in developer tools (Network tab) to check how long each request is taking, and where the bottleneck is.

If you’re certain the connection speed between your server and you is adequate, make sure you’re on the latest version of BlueMap, as there may have been optimisations since.

Q: Why is BlueMap using so much of my servers CPU?

When you install BlueMap for the first time, it needs to convert all of your world(s) into 3d models. This is a pretty intensive process, so it’s not strange at all to see BlueMap using up a lot of CPU power for a while after it’s been installed.

In the BlueMap config file core.conf you can set how many threads BlueMap will use for the conversion process. BlueMap runs asynchronously to your server-thread, so as long as the CPU isn’t maxed out, it should not slow down your server.

After the conversion process is done for the first time, it won’t ever have to render the whole map again! From then on, BlueMap will keep track of your world and convert only the chunks that change.

If you do /bluemap, you can see the progress of the conversions and an estimated time that is left.

Q: How can I add or remove maps?

To add a map, copy a map-config from the maps-folder next to the other config-files, open it and tweak the settings for your new map. To remove a map, just delete the config-file.
Read this guide for more info.

Q: How can I add SSL (HTTPS) to my map?

BlueMaps integrated webserver does not (and will not) support SSL on its own, but you can e.g. use NGINX to reverse-proxy your map and add SSL that way.

Q: How do I add authentication to my map?

BlueMap does not support authentication by itself. Instead, you could use http-basic-auth using an external webserver.

Known incompatibilities with other mods

  • JustEnoughIDs (jeid)
  • NotEnoughIDs
  • OpenCubicChunks
  • SlimeWorldManager