Install Add-ons on a Bedrock Dedicated Server (2026 Guide)

Published on | Updated

Bedrock add-ons on your own server: manifest.json UUIDs, world_behavior_packs.json, experiments, script permissions on BDS and what Geyser can and cannot load.

A Minecraft grass block drawn as a file folder

Your add-on works in single player, and now it has to run on a Bedrock Dedicated Server (BDS) or on a Java server that Bedrock players join through Geyser. This is the server half: the UUIDs in manifest.json, the world files that switch packs on, experiments, script permissions and the limits of Geyser. For downloading add-ons and importing them on Windows, Android and iOS, use our CurseForge Bedrock add-ons guide. Minecraft Education has its own guide.

Quick answer: To install add-ons on a Bedrock Dedicated Server, put each behavior pack folder in the server's behavior_packs folder and each resource pack folder in resource_packs. Then switch them on in the world folder: behavior packs in world_behavior_packs.json, resource packs in world_resource_packs.json, each as a pack_id and version copied from the header section of that pack's manifest.json. Restart the server. An add-on that needs an experiment, such as Beta APIs, has to arrive in a world that already has the experiment on, because server.properties has no setting for it. The same steps install Better on Bedrock on a dedicated server, or any other add-on. A Java server with Geyser can send Bedrock resource packs to Bedrock players, but it cannot run behavior packs.

The UUIDs in manifest.json

Every pack has a manifest.json at the top of its folder. Microsoft's manifest reference defines the parts a server cares about:

  • header.uuid identifies the pack. It goes into the world files as pack_id.
  • header.version is the pack version, written as [1, 0, 0]. The world files name it too.
  • modules[].uuid identifies a module inside the pack and "should be different from the pack's UUID". It never goes into the world files, but on BDS a script module's uuid names its config folder (see below).
  • header.min_engine_version is "the minimum version of the game that this pack was written for". If it is higher than your server version, update the server or download the add-on file made for your version.
  • dependencies lists what the pack needs. An entry with a uuid points at another pack; in Microsoft's example the behavior pack depends on its resource pack. An entry with module_name, such as @minecraft/server, asks for a script module version.

A trimmed behavior pack manifest, based on Microsoft's example:

{
  "format_version": 2,
  "header": {
    "name": "Vanilla Behavior Pack",
    "uuid": "ee649bcf-256c-4013-9068-6a802b89d756",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 0]
  },
  "modules": [
    { "type": "data", "uuid": "fa6e90c8-c925-460f-8155-c8a60b753caa", "version": [1, 0, 0] }
  ],
  "dependencies": [
    { "uuid": "66c6e9a8-3093-462a-9c36-dbb052165822", "version": [1, 0, 0] },
    { "module_name": "@minecraft/server", "version": "1.9.0" }
  ]
}

Here ee649bcf-... goes into world_behavior_packs.json, 66c6e9a8-... (the resource pack it depends on) goes into world_resource_packs.json, and the module uuid fa6e90c8-... goes nowhere.

Microsoft's reference also describes a format_version 3 manifest, which that page marks as preview, with versions as strings such as "1.0.0". For such an add-on, export a world with it active and use the world files the game writes.

To read the header values on a Linux server (an .mcaddon is "a zip file that contains .mcpack or .mcworld files", per Microsoft):

mkdir MyAddon && cd MyAddon
unzip -q ../MyAddon.mcaddon
for f in *.mcpack; do unzip -q "$f" -d "${f%.mcpack}"; done
for m in */manifest.json; do python3 -c 'import json,sys; h=json.load(open(sys.argv[1]))["header"]; print(sys.argv[1], h["uuid"], h["version"])' "$m"; done

You get one line per pack, such as MyAddon_BP/manifest.json ee649bcf-256c-4013-9068-6a802b89d756 [1, 0, 0]. If the .mcaddon holds pack folders instead of .mcpack files, skip the third line. If Python reports a JSON error, copy the values from a text editor.

Where Packs Go on Bedrock Dedicated Server

bedrock-server/
  bedrock_server
  server.properties
  permissions.json              player roles, not add-ons
  config/
    default/permissions.json    script modules
  behavior_packs/
    vanilla/                    Mojang's own packs, leave them
    MyAddon_BP/manifest.json
  resource_packs/
    MyAddon_RP/manifest.json
  worlds/
    Bedrock level/
      level.dat
      world_behavior_packs.json
      world_resource_packs.json

Microsoft's BDS getting started guide gives two places for a pack. "Packs installed in a folder for a world are only available when that world is running on the server", while packs in the top-level folders "are available on any world being run on the server". The 1.26.61.1 download already fills the top-level behavior_packs with Mojang's own packs (vanilla versions, chemistry, script and editor libraries, experiments), so put your folder next to them and remove nothing.

Copying a pack in does nothing on its own. The how-to file inside the server download says of both folders: "At the moment there's no way of activating them in a level." The world files below do the switching.

Two more folder pairs exist. development_behavior_packs and development_resource_packs appear on the first run, according to the Minecraft Wiki. system_behavior_packs and system_resource_packs hold packs an administrator applies across all worlds; their UUIDs "are protected, and will result in other user packs failing to load if using the same ID", the how-to warns.

On a Space-Node Minecraft server you upload pack folders and whole worlds with the panel's file manager or over SFTP.

world_behavior_packs.json and world_resource_packs.json

Both files sit in the world folder named by level-name in server.properties. Each holds a JSON list with one entry per pack, separated by commas:

[
  { "pack_id": "ee649bcf-256c-4013-9068-6a802b89d756", "version": [1, 0, 0] },
  { "pack_id": "header-uuid-of-your-second-pack", "version": [2, 1, 0] }
]

Four habits that prevent most failed loads:

  • If a file does not exist yet, create it with exactly that name.
  • Use the header uuid, never a module uuid.
  • Keep the version in step with the manifest. When an add-on update raises its version, change the world file to match.
  • Mind the order when two resource packs change the same thing. In the game's pack list, "The bottom-most pack loads first, then each pack placed above it replaces assets of the same name" (Minecraft Wiki). Set that order in the world's settings before you export, rather than guessing in the JSON.

Exporting gets both files right for you. Microsoft's world template guide shows that a world exported with packs active carries the packs in its own behavior_packs and resource_packs folders, both JSON files, and world_behavior_pack_history.json and world_resource_pack_history.json. Unzip that .mcworld into the server's worlds folder and point level-name at it; the export steps are in our CurseForge Bedrock guide.

Then restart: the Minecraft Wiki notes the server "needs to be restarted every time the server settings are readjusted, or plug-ins are added". /reload needs cheats and "Reloads all function and script files from all behavior packs", which helps while you tune a script, not when you add a pack.

Experiments on a Dedicated Server

The server.properties that ships with BDS 1.26.61.1 has no experiment setting. Experiments are saved in the world, so a world that needs one is made on a client first:

  1. In Minecraft on Windows, open a copy of the world or create a new one.
  2. Under Game settings > Experiments, switch on the toggle the add-on's page names.
  3. Activate the add-on's packs and test the world.
  4. Export the world, unzip it into the server's worlds folder and set level-name to the folder name, which "has to match exactly, including letter case" (Microsoft).

Work on a copy. Microsoft's experiments page warns: "Worlds that use experimental features cannot be restored to a non-experimental state." The Minecraft Wiki adds that an experiment disables achievements for that world. Its current add-on creator toggles are Upcoming Creator Features, Beta APIs, Experimental Creator Camera Features, Experimental Voxel Shape Features and Points of Interest, but the list "is subject to frequent changes", Microsoft says, so go by the add-on's page.

Beta APIs matters most for scripted add-ons. Microsoft's script versioning article says "In order to use -beta APIs, you must enable the "Beta APIs" experiment", and that "you may need to update the version number of manifest.json dependencies at every major release if you are using -beta APIs." On a server, an add-on on a -beta module can stop working after a BDS update until its author releases a new file, so check each pack's dependencies before you update.

Scripted Add-ons and the config Folder

BDS has two files called permissions.json. The one next to the server binary holds player roles. The one in config/default/ lists the script modules packs may use. In the 1.26.61.1 download it reads:

{
  "allowed_modules": [
    "@minecraft/server-gametest",
    "@minecraft/server",
    "@minecraft/server-ui",
    "@minecraft/server-admin",
    "@minecraft/server-editor",
    "@minecraft/debug-utilities"
  ]
}

@minecraft/server-net, which connects scripts to external web services, is not on that list. Microsoft's BDS scripting article recommends "keeping config/default/permissions.json basic and minimal" and granting extra modules per pack: make a folder inside config named after the script module's uuid (the modules entry with "type": "script", not the header uuid) and put a permissions.json in it that lists every module the pack uses.

config/
  default/permissions.json
  a8d43bd0-cffd-4988-949a-5105e14bb5f2/permissions.json

{
  "allowed_modules": [
    "@minecraft/server",
    "@minecraft/server-net"
  ]
}

These server APIs "are experimental as part of the Beta APIs program", Microsoft says, so the world needs Beta APIs on, and they do not work on Realms. The same folders can hold a variables.json with settings an add-on lets you change, and a secrets.json for values such as tokens, which scripts can only use in limited places such as HTTP headers.

Microsoft's property list also has script watchdog settings that the shipped server.properties leaves out. script-watchdog-memory-limit (default 250 MB) "Saves and shuts down the world when the combined script memory usage exceeds the given threshold". If a world with scripted add-ons shuts down under load, check that one first.

server.properties Lines for Add-ons

texturepack-required=true
content-log-console-output-enabled=true
content-log-file-enabled=true
content-log-level=warning
  • texturepack-required: "Force clients to use texture packs in the current world", says the shipped file. The Minecraft Wiki adds that players' global resources are then ignored and they must download the world's packs.
  • content-log-console-output-enabled: "Enables logging content errors to stdout", so pack errors show in the console. Off by default.
  • content-log-file-enabled: writes the same errors to a file.
  • content-log-level: the lowest level logged: "error", "warning", "info" or "verbose". The default is info.

Bedrock has no resource-pack-required setting; it is not in the 1.26.61.1 file or Microsoft's list. Java servers use require-resource-pack.

What Geyser Can and Cannot Load

Geyser lets Bedrock players join a Java server. On 3 November 2026 its supported versions page lists Bedrock 26.40 through 26.60 and Java 26.3.

Bedrock contentOn a Java server with Geyser
Resource packs (.zip or .mcpack)Yes, sent to Bedrock players from Geyser's packs folder
Behavior packs, add-ons with new mobs, items or scriptsNo
Custom items and blocksThrough Geyser's JSON mappings or API, plus a Bedrock resource pack
Java resource packsNot converted; Bedrock players need a Bedrock version

Resource packs. Geyser's packs page gives the folder: plugins/Geyser-<platform>/packs/ on plugin platforms such as Paper or Velocity, config/Geyser-<platform>/packs/ on Fabric and NeoForge, and packs/ for Geyser Standalone. After a restart or a Geyser reload, "players that connect will receive all packs that are in that folder."

Behavior packs. Geyser's answer to "Does Geyser support behavior packs/add-ons?" is: "No. These would require modifications on the Java server side, which isn't possible when Geyser is used on a proxy."

Custom items and blocks. Geyser maps them with JSON files in a custom_mappings folder in its config directory, with enable-custom-content: true under gameplay in config.yml (custom content). For items, "a Bedrock edition resource pack must also be supplied", and the old v1 format is deprecated since Geyser API 2.9.3 (custom items).

So on a Geyser server the gameplay comes from Java plugins or mods, and Bedrock resource packs only change what Bedrock players see. Every Space-Node Minecraft plan can run Bedrock directly or Java with Geyser, with three port allocations, so Geyser can have a port of its own. Our Geyser and Floodgate guide covers that setup.

When a Pack Does Not Load

Turn on content-log-console-output-enabled first, so content errors from your packs show up in the console.

What you seeLikely causeWhat to do
Server starts, add-on does nothingpack_id is a module uuid, or the version differs from the manifestCopy header.uuid and header.version again
Works in single player, not on the serverPacks are in the folder but not listed, or listed in another world folderCheck the world named by level-name
Custom mobs or items look wrong or invisibleResource pack not listed in world_resource_packs.jsonAdd the resource pack's header uuid
Some players see default texturesThey declined the downloadSet texturepack-required=true
Scripts do not runBeta APIs off in the world, or a module missing from allowed_modulesRe-export the world with the experiment on, or add a module folder in config
Broke after a server updateThe add-on uses a -beta script module that changedGet the add-on file for the new version
Other packs fail after adding a system packTwo packs share a protected UUIDRemove the duplicate

FAQ

How do I install Better on Bedrock on a dedicated server? Like any other add-on: both packs into the server's pack folders, both header UUIDs and versions into the two world files, and any experiment its download page names switched on in the world before you upload it. Our Better on Bedrock server guide walks through that add-on.

Should I use behavior_packs or development_behavior_packs on BDS? Use behavior_packs and resource_packs, the folders Microsoft's server guide documents. It does not describe the development folders that appear after the first run.

Can I turn on experiments in server.properties? No. The 1.26.61.1 server.properties has no experiment setting. Switch the experiment on in a world on a client, export it and upload it, and keep a copy, because the world cannot go back.

Can Geyser load Bedrock add-ons? Only the resource pack half. Geyser sends Bedrock resource packs to Bedrock players but cannot run behavior packs. Custom items and blocks need Geyser's mappings plus a plugin, data pack or mod that adds them on the Java side.

Can I put Marketplace add-ons on my Bedrock server? No. The Minecraft Wiki says Marketplace packs can be used on Realms, "but not to worlds in external servers". Use community packs from CurseForge or the creator's own site.

Sources

All opened on 3 November 2026: