Troubleshooting

Every entry here comes from a real report. If your problem is not listed, the run report written next to the world (benchmark.html) and the server console usually name the cause.

My world is flat or empty on my server

The most common one, and it is almost never a generation bug. A generated world is a complete world folder: level.dat, region/, and — if you extended the build height — datapacks/. Copying only region/ into a server, or pasting over a world while the server is running, gives a flat or half-broken world, because the server already holds its own level.dat in memory and writes it back on shutdown.

1. Open the world once in single-player. Accept the experimental-features prompt if it appears. If it looks right there, generation was fine and the rest is transfer.
2. Stop the server. Fully. Not restart-later, stopped.
3. Move the whole folder, keeping level.dat and datapacks/ with it. Either replace the server's world folder entirely, or import it with a plugin such as Multiverse-Core — the safer route on a server that already has a world worth keeping.
4. Match the version. A server older than the version you generated for cannot read the chunks. See below.

If the server logs Overlay "overlay_attributes" key formats is deprecated starting from pack format 82, that is a warning, not your problem — the extended-height datapack still loads. Current builds pick the metadata shape for your target version and drop the deprecated key, so it stops appearing once you regenerate with a version selected.

Which Minecraft version does the world target?

Meld writes the DataVersion of the version you pick under Minecraft version. Only versions whose constants were read out of a real client are offered, because a guessed value produces a world that loads and then quietly misbehaves.

The rule is one-directional: a newer client can open an older world, an older client cannot open a newer one. To go backwards — you generated for 1.21.x and your server is on 1.20.1 — convert the finished world with chunker.app. Meld does not down-convert, and pretending to would cost you blocks that did not exist yet in the older version.

Extended build height additionally needs the datapack format for that exact version, so it is offered only where that number has been verified too.

Map data fails, or is rate limited

Buildings and roads come from Overpass, a free shared service with per-IP limits. What you may see:

• Rate limited (429) — too much asked too quickly. Meld rotates through several mirrors and retries; everything already fetched is cached on the shared grid, so a re-run does not re-download it.
• Server overloaded (403) or server unavailable (5xx) — the public instance is busy. Same handling: mirrors, then retry.
• Nothing comes back at all, on every network you try — some networks and regions block the Overpass hosts outright.

The permanent fix for all three is to stop calling out: download a .osm.pbf extract from Geofabrik and bake it into the OSM data pack. Generation then reads map data from disk with zero Overpass calls, and every overlapping project reuses it. Baking a country takes minutes and pays for itself the moment you build the same region twice.

A bake is cancellable: Stop bake aborts within about a second, and tiles already written are kept.

What does bake lighting actually do?

It pre-computes each chunk's light data and writes it into the region files. That is only useful to things that read the world off disk without loading it in-game: LOD mods such as Voxy and Distant Horizons, and map renderers. Minecraft itself re-lights chunks as you load them, so in normal play you will not see a difference.

It is not a fix for a world that looks dark, it has nothing to do with buildings, and it makes generation slower and region files bigger. Leave it on if you plan to hand the world to Voxy; turn it off for the fastest build.

The size or time estimate was way off

Estimates start from a model — regions covered, build height, caves, baked lighting — and a model is a guess. As soon as a run finishes, Meld measures what actually landed on disk per region and uses that measurement for the project from then on, so the second estimate is far better than the first.

The two settings that move it most are Extend build height (a 2,000-block world writes several times the sections a 384-block one does) and Caves. If your estimate looked small next to what you got, check whether both were on.

"Selection too big to plan"

Meld refuses a plan past roughly 20,000 cells, and it refuses it before building the list rather than dying halfway through. The whole planet at 1:1 with 4-region cells is about 200 million cells: tens of gigabytes of bookkeeping before a single block is placed.

Three ways out, cheapest first:

• Bigger cells. Doubling the cell size quarters the cell count. 16- or 32-region cells are normal for continental builds.
• Smaller scale. 1:2 is a quarter of the blocks of 1:1.
• A smaller area, or build it in pieces — each project keeps its own selection, and the render queue runs them back to back unattended.

Workers, threads, and why a build feels slow

Generation is mostly CPU-bound. Keep workers × threads-per-worker at or under your logical CPU count; going over oversubscribes and gets slower. Recommend settings probes your CPU, RAM and save-disk speed and fills the machine — on a big CPU it now suggests more than the old fixed maximum of eight workers.

RAM and disk are the secondary caps: each concurrent worker holds a cell in memory and writes a burst of regions at the end of it. If you are swapping or the drive is pegged, fewer workers with more threads each beats the reverse.

Two phases are not the worker count's fault: the first-time elevation and OSM prefetch, and the export/compression pass afterwards. Both report as their own phase.

It will not start, or dependencies fail

Meld needs Python 3.9+; the launcher builds its own .venv and installs the rest. If an optional dependency has no wheel for your platform, the launcher falls back to the core set and keeps going — offline .pbf baking (osmium) is the one feature that needs an optional package.

Run python meld_launch.py --check to see what is present without changing anything. On Windows, running .\meld.bat from PowerShell works when double-clicking does not.

Things in the world that look wrong

• Boats, cranes or other props look enormous on a scaled-down world. Props are fixed-size schematics; they do not shrink with the scale. Below roughly 1:3 they are skipped by default. --props-min-scale 0 places them anyway, or turn individual families off.
• A large natural area drawn as an outline with untouched ground inside. Fixed: very large OSM polygons used to have their fill skipped while the border was still painted. Regenerate with a current build.
• Terrain steps at cell edges. The elevation lock must be set — it is what keeps every cell on one height scale. A cell built before the lock needs rebuilding.
• Sand along the coast, rock inland. That is the land-cover classification rather than a bug: shorelines are sand, and inland bare ground follows its climate.