Answers to the questions server owners ask most, and what to check when something doesn't work.
The short answers to common questions. Each one links to the page with the full details.
Connecting
Section titled “Connecting”Players can’t connect from outside my network
Section titled “Players can’t connect from outside my network”Basalt uses two ports, and both must be open in the firewall and forwarded on your router:
| Port | Protocol | Used for |
|---|---|---|
| 19132 | TCP | Clients start their connection here |
| 19133 | UDP | Game traffic |
If the machine is behind NAT, also put its public address in advertised_addresses in basalt.toml, so clients are told where to send game traffic. Restart Basalt after changing the file. See Ports.
Which Bedrock version do players need?
Section titled “Which Bedrock version do players need?”Basalt targets Minecraft 1.26.60 (network protocol 2225). Players join from the normal Bedrock client on that version.
Players are asked to sign in, or can’t join without Xbox
Section titled “Players are asked to sign in, or can’t join without Xbox”With online_mode on (the default), Basalt checks every player’s Xbox sign-in, and it needs an internet connection at startup to fetch the keys for that. Turning online_mode off lets anyone join under any name, including an operator’s, so only do that where nobody else can reach the machine. See Configuration.
Worlds
Section titled “Worlds”Can I use my BDS or single-player world?
Section titled “Can I use my BDS or single-player world?”Yes. Basalt uses the vanilla world layout, so stop Basalt, copy the world folder into worlds/, set world in basalt.toml to its folder name and start Basalt again. Work on a copy: Basalt writes to the world’s database as it runs. See Use an existing world.
Where are the Nether and the End?
Section titled “Where are the Nether and the End?”Basalt has one dimension for now, the overworld. The full list of what’s missing is on Vanilla parity.
Settings
Section titled “Settings”I changed basalt.toml and nothing happened
Section titled “I changed basalt.toml and nothing happened”Settings are read once, at startup, so restart Basalt after editing the file. A misspelled or unknown setting stops Basalt from starting, and it says which one. The config builder writes a file with only valid settings.
How do I make myself an operator?
Section titled “How do I make myself an operator?”Type op YourName in the terminal. Operators are stored by Xbox account (XUID), so renaming a gamertag doesn’t change operator status. See Permissions, allowlist and bans.
Plugins and addons
Section titled “Plugins and addons”Do my BDS scripts and addons work?
Section titled “Do my BDS scripts and addons work?”Mostly. Plugins run against Basalt’s port of @minecraft/server, so most scripts written for vanilla work as they are; Differences from BDS lists what doesn’t. Custom items and entities from behaviour packs load too; Addons lists which components are supported.
I added a plugin or addon and it doesn’t show up
Section titled “I added a plugin or addon and it doesn’t show up”Put each one in its own folder under plugins/ and restart Basalt. Addon content (custom items and entities) is read only at startup, so /reload doesn’t pick it up. A plugin needs its manifest.json and scripts/ folder.
Performance
Section titled “Performance”The server is lagging
Section titled “The server is lagging”Run /status in game as an operator (or status in the terminal) while it lags. Basalt is healthy at 20.00 TPS, with each tick well under 50 ms. The same command shows chunks, entities and any plugin that is slowing things down. Performance explains which settings to change.
Running Basalt
Section titled “Running Basalt”How do I stop Basalt without losing anything?
Section titled “How do I stop Basalt without losing anything?”Type stop in the terminal or press Ctrl+C once. Basalt disconnects players, saves them and the world, then exits. Pressing Ctrl+C a second time while it’s saving exits straight away and loses what wasn’t saved yet.
How do I update Basalt?
Section titled “How do I update Basalt?”Pull the new source and build again. New settings are added to your existing basalt.toml the next time it starts; what you wrote is kept. See Updating.
Something else is wrong
Section titled “Something else is wrong”Check the open issues on GitLab, or ask on Discord. To report a bug, How to report an issue lists what to include.