How to Install a Modded Map on Your BeamMP Server

Context

You manage a BeamMP server at Winheberg and want to move past the default map to offer your players something more original? Whether it's driving on Bajarama, Roane County, Garfield Heights, or any other community map, installation takes just a few minutes through your gaming panel.

This guide walks you through how to add a modded map to your BeamMP server, how to correctly identify its internal name (the most common mistake), and what to do if the map doesn't load.

Prerequisites

Before you start, make sure you have the following.

An active BeamMP server on your Winheberg gaming panel
The .zip file of the map you want to install
A trusted source to download the map from (the official BeamNG.drive Repository, BeamMP forums, etc.)

Only download maps from trusted sources. As with mods in general, .zip files can contain malicious code or corrupted files. Prefer the official BeamNG repository or well-known community creators.

1. Upload the map to your server

The map file needs to be placed in a specific folder to be detected by BeamMP.

Log in to your Winheberg gaming panel
Select your BeamMP server
In the side menu, click Files
Navigate to the Resources folder, then Client
Drag and drop your .zip file into this folder (don't extract it, BeamMP reads archives directly)

The full path should look like this.

/home/container/Resources/Client/your-map.zip

The panel enforces a 100 MB upload limit through the web interface. Most BeamMP maps far exceed this limit. If your .zip is over 100 MB, you'll need to use an SFTP connection to upload your map. Your SFTP credentials are available in your server's Settings section (host, port, username), and the password is the same as your panel account's. Use a client like FileZilla or WinSCP to connect and drop your file directly into Resources/Client.

The Client folder is specifically for resources automatically sent to players when they connect. Don't confuse it with the Server folder, which holds server-side scripts.

2. Identify the map's internal name

This is the most important step, and the one that causes the most trouble for beginners. The .zip file's name isn't the map name BeamMP needs. You need to find the internal name used by the game engine.

Method 1, from the download site

Most sites that distribute BeamNG maps list the map's internal name in the description, often in the form levels/internal_name/info.json. That's the information you need.

Method 2, inspect the .zip's contents

If that info isn't available on the site, open the .zip file with archive software (without extracting it). You'll find a folder structure that looks like this.

levels/
  └── map_name/
        ├── info.json
        ├── main.terrain.json
        └── ...

The folder name under levels/ is exactly the internal name you need.

Concrete examples

Here are a few examples to help you visualize it.

Map	Internal name	Full path
Default map	`gridmap_v2`	`levels/gridmap_v2/info.json`
Bajarama	`bajarama`	`levels/bajarama/info.json`
Roane County	`roane_county`	`levels/roane_county/info.json`

3. Configure the map path in the panel

Once you've identified the internal name, you need to tell BeamMP to load this map on startup.

In the panel's side menu, click Startup
Find the Map field
Replace the current value with your map's full path, in the levels/internal_name/info.json format

For example, for the Bajarama map.

levels/bajarama/info.json

Save the changes

The expected format is always levels/NAME/info.json. No leading slash, no absolute path, no .zip extension. If you put anything else, the server won't find the map and will fall back to the default map (or refuse to start).

4. Restart your server

For the changes to take effect, you need to restart your BeamMP server.

Go back to your server's main page in the panel
Click Restart (or Stop then Start if needed)
Watch the console to make sure the server starts correctly with the new map

If the map loads without errors in the logs, you can connect to the server from your BeamMP client to test it in-game.

If you run into trouble

Here are the most common errors when installing a modded map.

❌ The server starts but loads the default map

The path you entered in the Map field is incorrect. Check the following.

The map's internal name is spelled correctly (case-sensitive, no spaces)
The format is exactly levels/NAME/info.json, with no leading slash
The .zip file is indeed in Resources/Client and nowhere else

❌ Map loading error in the console

If you see an error like "Could not find level" or "Map not found" in the console, the server can't read the file. Check the following.

The .zip file isn't corrupted (try opening it with archive software)
The .zip does contain a levels/ folder at its root
You didn't accidentally extract the .zip (BeamMP needs the archive intact)

❌ The map works in solo but not on the server

Some maps are designed only for BeamNG.drive's solo mode and aren't adapted for multiplayer (unsynced objects, incompatible scripts, etc.). Check the map's page to see if it's explicitly BeamMP-compatible.

❌ My players can't connect after adding the map

The .zip file may be too large for your players to download quickly. Check the following.

The file size is reasonable (beyond 500 MB, some players may experience timeouts)
Your players have a connection stable enough to download the map on first launch
The server isn't overloaded on bandwidth at the time players connect

Best practices

A few recommendations for managing your modded maps smoothly.

Back up your server before every map change, especially if you have many mods depending on the current map
Test the map in solo in BeamNG.drive before deploying it on your server, to check that it loads without errors
Warn your players about a map change, especially if the new map is heavy to download
Limit the number of active maps, a BeamMP server loads only one map at a time, but keeping several .zip files in Resources/Client increases the initial download size for players
Prefer maps optimized for multiplayer to avoid lag and desync

Need help?

If your map doesn't load despite these steps, or if you run into a console error you can't interpret, our team is here. Open a ticket in the Technical department from your client area, fill in the Related product field with the server in question, and attach the server's startup logs along with the exact name of the map you're trying to install.

Your BeamMP server is ready to welcome your players to a new map, safe travels 🛣️