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


Q: Where can I open my map?

By default, it’s your servers public ip-address (e.g. and the port (8100) like this:
(Make sure you replace 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: Why is BlueMap using so much of my 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: I have black/pink-checkered blocks on my map!

Read this:

Q: My block-textures are messed up when I zoom in on the map!

First, 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.
You can also try to clear your browser-cache completely. (F12 -> Network -> [x] Disable cache -> F5)

If that doesn’t help you might have changed some bluemap-settings that require a complete re-render of the map: Just use /bluemap purge <map-id> to delete and re-render the entire map. Then clear your browser-cache again, and it should be fixed :)

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.
  • Make sure that the world:-setting in your map-config is set to the correct world-folder.
  • 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.
    You can try to use a plugin like LightCleaner to fix chunks that don’t have proper lightdata in your world.

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: The map (web-app) is really slow (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: 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.

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: My map disappears when I zoom in!

This happens when BlueMap is trying to load the hi-res tiles, but can’t find them for some reason.
This could be caused by one of two things:

  • You’ve set save-hires-layer to false in your map’s config.
    If this is the case, make sure to set the hires-slider-default to 0 in webapp.conf and set the “Render Distance - Hires Layer” slider down to 0 in the webapps settings-menu.
  • You haven’t set up your external webserver correctly yet.
    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: 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