My pack loads in singleplayer but not on the server, why?

The most common causes are: the pack isn't registered in world_behavior_packs.json or world_resource_packs.json, the level-name in server.properties doesn't exactly match the world folder name (including spaces), or the pack requires Beta APIs which must be enabled on the world in the Bedrock client before uploading.

Which UUID do I use from manifest.json?

Use the uuid listed under the 'header' section, not the one under 'modules'. The pack_id in your world JSON files must match the header UUID.

Do I need to restart the server after changing pack JSON files?

Yes. Stop the server before making any changes to pack config files, then start it again once your edits are saved.

Why does my server create a blank new world instead of loading mine?

The level-name in server.properties doesn't match your world folder name. If your folder is named 'My World' (with a space), level-name must be set to exactly 'My World', not 'MyWorld'.

What if world_behavior_packs.json or world_resource_packs.json doesn't exist in my world folder?

Fresh worlds, including ones generated by BDS itself or copied from a Bedrock client that had no packs applied, often have no pack JSON files. Create them by hand inside the world folder. The file names must be exactly world_behavior_packs.json and world_resource_packs.json, and the contents must be a valid JSON array (start with [] if you have no packs yet).

I downloaded a .mcpack or .mcaddon file. Can I upload it directly?

No. The Game Control Panel's File Manager cannot extract .mcpack or .mcaddon archives. Extract them on your own computer first (rename the extension to .zip and use your OS's built-in unzip tool, or open them with an archive tool like 7-Zip), then upload the resulting folder via SFTP. A .mcaddon usually contains multiple .mcpack folders inside; upload each to the appropriate behavior_packs or resource_packs directory.

Is uploading the pack folder enough to make it load?

No. A pack only loads once its header UUID is registered in world_behavior_packs.json or world_resource_packs.json inside the world folder that level-name points at. Uploading on its own changes nothing in-game.

How to Install Addons on Your Minecraft Bedrock Server

An addon loads on a Bedrock server only when the pack folder is on the server and its header UUID is registered in the world’s pack JSON files. Uploading the pack on its own changes nothing in-game.

Quick answer

Extract .mcpack and .mcaddon files on your own computer. They are renamed .zip archives, and BDS reads folders, not archives.
Upload behavior pack folders to /behavior_packs/ and resource pack folders to /resource_packs/ over SFTP, with manifest.json directly inside each folder.
Register every pack in world_behavior_packs.json and world_resource_packs.json inside your world folder, using the uuid from the manifest’s header section.
Check level-name in server.properties matches your world folder name exactly, then start the server and watch the console.

If you run your world on our Minecraft Bedrock server hosting, you upload these pack folders over SFTP.

Step 1: Upload Your Pack Folders

Addons download as .mcpack (a single pack) or .mcaddon (a bundle of packs). Both are renamed .zip archives, and the File Manager cannot extract either extension, so unpack them on your own computer first: rename the file to .zip and use your operating system’s built-in unzip tool, or open it directly with an archive tool like 7-Zip.

Connect to your server using SFTP
Upload each behavior pack folder to /behavior_packs/ and each resource pack folder to /resource_packs/

Each pack must be a single folder with a manifest.json file directly inside it, not nested in a subfolder. A .mcaddon usually holds several pack folders, so upload each one to whichever directory matches its type.

Step 2: Find the Pack UUID from manifest.json

Open the pack’s manifest.json and copy the uuid listed under the header section. The modules UUID looks identical and is the most common reason a pack silently fails to load.

{
  "format_version": 2,
  "header": {
    "name": "My Addon",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",  ← use this one
    "version": [1, 0, 0]
  },
  "modules": [
    {
      "uuid": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",  ← NOT this one
      "type": "data",
      "version": [1, 0, 0]
    }
  ]
}

Step 3: Register Packs in the World JSON Files

Inside your world folder (found under /worlds/ on the server), there are two files that tell BDS which packs to load:

world_behavior_packs.json lists your behavior packs
world_resource_packs.json lists your resource packs

Each file must be a valid JSON array with one entry per pack:

[
  {
    "pack_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "version": [1, 0, 0]
  },
  {
    "pack_id": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
    "version": [2, 1, 7]
  }
]

The pack_id must be the header UUID from Step 2. The version must match the version array in the pack’s manifest.json header.

If the file doesn’t exist, create it

Fresh worlds, including ones generated by BDS itself or copied from a Bedrock client that had no packs applied, often have no world_behavior_packs.json or world_resource_packs.json file. In that case, create the file by hand inside your world folder.

The file names must be exactly world_behavior_packs.json and world_resource_packs.json (no extra extensions, no leading underscore, all lowercase). The contents must be a valid JSON array. Start with [] if you have no packs yet, then add your entries as shown above.

Common JSON errors that prevent packs from loading

Error	What to fix
`//` comment in the file	JSON does not support comments. Remove any `//` or `/* */` lines
Missing `,` between entries	Every `}` that closes an entry (except the last one) needs a trailing `,`
Period instead of comma (`}.`)	Change `}.` to `},`
Leading space in `pack_id` value	The UUID must start immediately after the `"`. Remove any spaces
Mismatched entry count	Every `pack_id` must correspond to a folder that actually exists in `behavior_packs/` or `resource_packs/`. Remove entries for packs that aren’t uploaded
File saved with a BOM	Some editors save UTF-8 with a byte-order mark, which BDS cannot parse. Re-save as plain UTF-8

Use a JSON validator (such as our JSON Validator tool) to check your files before starting the server if you’re unsure.

Step 4: Verify level-name Matches Your World Folder

Open server.properties and check the level-name value. It must exactly match the name of your world folder inside /worlds/, including any spaces or capitalization.

# server.properties
level-name=My World   ← must match the folder name exactly

If level-name=MyWorld but your folder is named My World, BDS auto-creates a blank MyWorld folder and loads that instead. Your pack registrations in My World are never read.

Step 5: Enable Beta APIs (if packs use the Script API)

Some addons use the Bedrock Script API for custom gameplay logic, UI, or entity behavior. These need the Beta APIs experiment enabled on the world, which is a client-side toggle: download the world, turn on Beta APIs under Experiments in your Bedrock client, then re-upload it. See Enabling Experimental Features for the full procedure.

Without it, those packs fail with errors referencing @minecraft/server or @minecraft/server-net.

Step 6: Start the Server and Check the Console

Start your server and watch the console output. A working addon load looks like:

[INFO] Loading resource pack: My Addon v1.0.0

If a pack fails, the console shows which pack and why.

Common console error messages

Console message	Cause
`broken resource manifest`	manifest.json is missing, malformed, or uses an incorrect UUID
`Pack not found`	The `pack_id` in your world JSON has no matching folder in `behavior_packs/` or `resource_packs/`
`Script module failed to load`	Beta APIs experiment is not enabled on the world
`block definition error`	The pack uses block definitions incompatible with your current BDS version. Check for a pack update

Need a hand?

Stuck on a pack that still will not load? Reach out to our team anytime. Send us the pack name and your console output and we will take a look. If we can fix it on your server for you, we will.