ReferenceReference

Troubleshooting and FAQ

Fixes for key conflicts, missing terrain, slow frame rates and the map turning itself off, plus safe mode, storage and frequently asked questions.

Start with the message you see, your Atlas version (under Mods) and whether the problem happens in one world or in every world. Keep logs/latest.log before you restart the game. For help, ask in Orbital's Lounge on Discord (opens in a new tab), and consider sending an Atlas report.

M opens another map or mutes voice chat#

Open Options > Controls > Key Binds and give Atlas's World map / Quick Tune (hold) its own key, or give the other mod's action another key. Xaero's World Map, FTB Chunks and Simple Voice Chat may also use M, and JourneyMap may share = and - with Atlas's minimap zoom.

Atlas names each clash with its world map key once in chat and never changes your keys itself. A binding saved by an older installation can differ from today's defaults; see Controls and commands.

The minimap is missing or covers another HUD element#

Check Minimap > Show minimap, and whether the game's HUD is hidden with F1. A server can turn the minimap off; Atlas tells you when it does, and the world map still works. Move the minimap with Position, or change its Size.

With another map mod installed, two minimaps are expected. Hide or move one of them in its own settings.

The map looks empty#

What you seeWhat it means and what to do
Illustrated parchment outside the land you have exploredUnexplored ground. Explore to map it.
Explored · terrain not loaded yetYou have been there, but its terrain is still loading. Wait a few seconds or zoom in.
Greyed parchment over places you visitedSaved terrain is still loading, or was only roughly recorded. Wait, zoom in, or visit the place again. Report gaps that stay.
A saved map of another dimensionA read-only, flat view of that dimension. Go back to the live map for detail.
Cave mapping is disabled by this serverThe server's rules turn cave maps off. In the Nether and other dimensions with a roof this also stops the layer view.
Orbital Atlas turned offThe map switched itself off after an internal error. See below.

The map records the chunks your own game receives. Fast travel, a short render distance or slow world generation can leave rough terrain or gaps; visit the area again to replace them with full detail. If close-up block textures of a place you saw long ago show as plain colours, the Block texture storage limit was reached; they come back when you see the place again, and you can raise the limit under Settings > Storage.

Atlas turned its map off#

If Atlas hits an internal error, it switches its map off with Orbital Atlas turned off instead of crashing the game. Your game keeps running.

  1. While the session is still open, send an Atlas report if you can. It includes Atlas's recent warnings and errors.
  2. Type /atlas reenable. The map drops what it had built and starts again.
  3. If the same thing happens again, tell us what you were doing. After the third error in one session, the map stays off until you restart the game.

If the map is off because this world's map data was written by a newer Atlas, or has a format stamp this Atlas cannot read, keep the files as they are and update Atlas, or restore the complete backup you made before updating. Re-enabling the map does not make such data safe to open.

Slow frame rate or slow map updates#

Open Settings > Advanced > Performance. Medium is the default; Low does less work to keep the map fresh. A preset sets Update speed, Edit replay, Minimap refresh, Height shadows, Animated frontier and Faces within together; see the settings reference.

  • For a low frame rate, try Low, make the minimap smaller, and zoom the world map in a step.
  • If the map fills in slowly and you have frames to spare, raise Update speed. Higher values can cost frame rate.
  • Near big farms or machines, set Edit replay to Slow.
  • Give the game at least 4 GB of memory, or more if your modpack asks for it.
  • Compare with shader packs off, changing one thing at a time.

The world map does not pause the game: the world and other mods keep running while it is open. A very wide view of a large explored world asks Atlas to load and draw much more terrain.

For a useful performance report, create an empty file named config/orbitalatlas-mapperf, restart, reproduce the slowdown, and send an Atlas report within ten minutes. Delete the file afterwards. Tell us your frame rate with the world map open and closed, and whether you were walking, flying or standing still.

Safe mode#

Type /atlas safemode on, then restart Minecraft. Safe mode turns off Atlas's faster terrain upload paths without touching your saved map. On Windows and Linux the map may fill in more slowly.

If you cannot get into a world, close the game and add this line to the plain-text file config/orbitalatlas-props (create it if it does not exist):

orbitalatlas.safemode=true

To leave safe mode, type /atlas safemode off and restart, or remove the line with the game closed. Tell us whether safe mode helped.

My map or waypoints seem to be gone#

Check that you are in the same instance and connected through the same server address. Each launcher instance has its own Atlas data, and joining the same server under a different address, or renaming or moving a singleplayer world, starts a separate map. The old files stay on disk.

Go back to the original instance and address. If you moved to a new instance on purpose, close the game and copy a complete backup of orbitalatlas/ and config/orbitalatlas* into it. Do not overwrite your only copy, and never merge parts of different backups.

Changing your resource packs keeps your saved map. Places you visit again get the new textures; distant places keep the old look until you go back.

If your data still seems missing, stop playing that world, keep its files and ask for help. Do not clear explored areas or waypoints to fix missing terrain.

Storage warnings#

Settings > Storage > Map storage limit is 8 GB by default for the saved maps of all your worlds. When they pass it, Atlas warns you and offers Remove oldest maps (it lists exactly which maps would go and asks first), Raise limit or Dismiss for this session. The map you have open is never offered for removal.

Atlas paused saving the map means the disk is nearly full: Atlas has stopped saving new map pieces rather than deleting anything. Free some space. /atlas data shows how much each world uses. Waypoints and explored areas are not part of the limit.

Rebuild the saved map only when asked#

Do this only if we ask you to after a report. The terrain folder holds the saved map of the places you visited; a fresh map refills only as you revisit them.

  1. Close the game and back up orbitalatlas/ and config/orbitalatlas*.
  2. Rename orbitalatlas/terrain to an unused name such as terrain.old.
  3. Start the game and see whether the problem changes.
  4. To go back, close the game, move the new terrain folder aside, and rename terrain.old back to terrain.

Waypoints, explored areas, region names, trails, routes and settings are elsewhere and are not affected. Never delete orbitalatlas/exploration/ or orbitalatlas/waypoints/ to fix terrain.

Known limitations in this beta#

AreaWhat you may noticeWhat to do
Wide world mapsLarge explored areas can show parchment for a moment while terrain loads, and very wide views can lower the frame rate.Wait or zoom in. Report gaps that stay after loading settles.
Fast travelNewly loaded terrain can stay rough until full detail catches up.Slow down or revisit; tell us your travel speed.
Automatic cutsVery large or unusual buildings can get the wrong cut or show a roof.Pick a level with the View button, or use Levels or a manual floor; send a screenshot.
Shader packsThe world behind the full-screen map can look wrong with some shader packs. Shader packs are lightly tested.Tell us the shader pack and its version.
GraphicsAMD, Intel and Linux are supported on a best-effort basis.Try safe mode if needed, and include your graphics card and driver.
Other dimensionsSaved maps of other dimensions are a flat, coarser view, and modded dimensions with unusual terrain have had little testing.Use the live map in that dimension for detail.
Team playTeam features on servers with mixed Atlas versions need more real-world testing.Keep server and client on the same Atlas version.

Common questions#

Does the server need Atlas? No. Install it in your game for the map. On a server it adds team play, far teammates' positions and fair-play rules.

Can I keep another map mod? Yes. Give the maps different keys and hide one minimap if you like. Atlas can import Xaero's Minimap and JourneyMap waypoints, with a preview and Undo.

Is the map an x-ray? No. Ores below the surface are drawn as the rock around them, and the cave view shows only caves you have explored, unless you turn on Show all underground where the server allows it.

Why are radar, cave views, Seek or teleport missing? The server can turn them off, and teleport also needs operator permission. A setting in your game cannot override the server.

Why does the Nether look like a cave? It has a roof. Atlas maps the layer you are on instead of the roof.

Will removing Atlas break my world? No. Atlas adds no blocks or items. Remove the jar with the game closed. Its map files stay until you delete them, and anything you shared on a server stays there until it is removed.

Where do I report a bug? In Orbital's Lounge on Discord (opens in a new tab). Include your Atlas version, operating system, graphics card, launcher, memory, modpack and what you were doing. If you sent an Atlas report, say roughly when. A report does not include crash files: for a crash, keep logs/latest.log and the newest file in crash-reports/, and read them for names, chat and paths before you share them.

Search settings, controls and guides. Use Tab to move through results.