MTR Surveyor MTR × Xaero
GitHub

Documentation

Troubleshooting & FAQ

Common issues and how to fix them.

No waypoints appear

Check, in order:

  1. Is the mod loaded? Run /mtrsurveyor mode. If it says “Unknown command”, the jar isn’t in the right mods/ folder or Forge didn’t load it. Check the game log for an mtrsurveyor load line.
  2. Is MTR loaded and present in this world? MTR Surveyor only maps data MTR gives it. If the server doesn’t run MTR, there’s nothing to map.
  3. Is Xaero’s Minimap installed? Waypoint sync needs it. The mod will log whether it detected Xaero on startup.
  4. Is sync enabled? /mtrsurveyor config enabled should report true. If not, run /mtrsurveyor config enabled true.
  5. Are stations visible? /mtrsurveyor config showStations should report true.
  6. Force a sync: /mtrsurveyor syncWaypoints. Watch chat for the response — if it says Xaero's Minimap is not installed!, that’s your problem.
  7. Open the world map. Xaero waypoints may not show on the small minimap if you’re far away; open the full world map (Y by default) to confirm.

Waypoints are underground / at the wrong height

This is exactly what MTR Surveyor fixes — if you’re still seeing it:

  • Station mode places waypoints at the average platform height for the station. If a station has platforms at very different levels, the average may sit between them.
  • Platform mode places each waypoint at the exact platform Y. Switch to it: /mtrsurveyor mode platform.

If heights look wrong in platform mode too, the MTR data for that platform may be incomplete on your client — try opening the MTR dashboard once (this populates the second data source), then /mtrsurveyor syncWaypoints.

Waypoints are duplicated or stale

Every sync pass first removes every waypoint whose name starts with [MTR] , then re-adds the current set. If you see stale duplicates:

  • Force a resync: /mtrsurveyor syncWaypoints.
  • If it persists, there may be a Xaero version mismatch. Ensure you’re on Xaero’s Minimap ≥ 25.3.10.
  • As a last resort, you can manually delete the [MTR] waypoints from Xaero’s waypoint screen; the next sync will recreate the correct set.

The route overlay doesn’t show

  1. Is Xaero’s World Map installed? The route overlay requires it (waypoints only need the Minimap).
  2. Is the toggle on? Open the world map and click the MTR widget in the top-left. It should turn green.
  3. Is there route data? The overlay reads MTR’s SimplifiedRoutes and Routes. If your network has no routes defined, there’s nothing to draw.
  4. One-shot guard. If the renderer ever threw an exception, it disables itself for the session to avoid log spam. Check the game log for the original error, then report it. Restarting the client re-arms the guard.

/mtrsurveyor syncWaypoints says “Xaero’s Minimap is not installed!”

You’re missing Xaero’s Minimap, or it failed to load. The mod only checks for xaerominimap (mod ID). Install Xaero’s Minimap for 1.20.1 (≥ 25.3.10) and relaunch.

The game crashes on startup

This should not happen — XaeroMixinPlugin skips the Xaero world-map mixins when Xaero’s World Map isn’t present, and all Xaero-coupled code is wrapped in try/catch(NoClassDefFoundError). If you do see a crash:

  1. Check the crash report for the first Caused by: line.
  2. Verify your Forge version is 47.2.0+ for 1.20.1.
  3. Verify MTR is 4.0.2-hotfix-1+.
  4. Open an issue with the full crash report and game log.

It works in single-player but not on my server

MTR Surveyor is client-side — if it works in single-player, it works on servers too. If waypoints don’t appear on a specific server:

  • The server must be running MTR and have an actual transit network.
  • Some servers throttle or delay MTR data sync. Move around / load chunks to trigger MTR data updates, then /mtrsurveyor syncWaypoints.
  • If the server runs a very old or very new MTR build that changes the client data API, sync may silently fail. Check the compatibility matrix.

How do I see debug output?

Set debugLog = true in .minecraft/config/mtrsurveyor.toml (or it’s a runtime option you can toggle by editing the file and reloading). Every sync event will be logged to the console. Turn it back off when you’re done — it’s noisy.

FAQ

Does this work on Fabric?

No. MTR Surveyor is Forge 1.20.1 only.

Can I use it on a server I don’t control?

Yes — that’s the whole point. Install it on your client, join any MTR-running server, and it just works.

Does it send anything to the server?

No. It only reads MTR data your client already received, and writes to Xaero’s local waypoint files. No packets, no network traffic from MTR Surveyor.

Will it lag my game?

Sync is throttled to once every 5 seconds (100 ticks) and only runs when MTR data actually changed. The route overlay renders once per frame but uses a single flushed buffer. On typical networks the impact is negligible.

Where are the waypoints stored?

In Xaero’s own waypoint files under .minecraft/XaeroWaypoints/. MTR Surveyor just calls Xaero’s API to add/remove them; it doesn’t store anything itself.