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. Decompress 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.

How to Install Addons on Your Minecraft Bedrock Server

Install addons (behavior packs and resource packs) on your Minecraft Bedrock server by uploading the pack folders, registering each pack in the world’s JSON configuration files, and ensuring the server is pointed at the correct world.

Step 1: Upload Your Pack Folders

Use SFTP for this step. The Game Control Panel’s File Manager cannot extract .mcpack or .mcaddon archives, and addon downloads typically arrive in those formats. SFTP also handles deep folder structures more reliably than drag-and-drop into the panel.

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

Each pack should be a single folder containing a manifest.json file directly inside it, not nested in a subfolder.

Check for double-nested folders

A common upload mistake results in a structure like behavior_packs/MyPack/MyPack/manifest.json. BDS expects behavior_packs/MyPack/manifest.json. If you see an extra inner folder with the same name, move its contents up one level and delete the empty inner folder.

Do not delete the vanilla BDS packs

The behavior_packs/ folder contains vanilla BDS packs that Bedrock needs to register biomes and base game content. Deleting or replacing these folders will crash the server immediately on startup. Only add your addon folders. Do not remove anything that was already there.

Step 2: Find the Pack UUID from manifest.json

Each pack has a manifest.json file. Open it and find the uuid listed under the header section. This is the value you need for your pack JSON files.

{
  "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 require the Beta APIs experiment to be enabled on the world. If this toggle is missing, those packs will fail with errors referencing @minecraft/server or @minecraft/server-net.

To enable Beta APIs:

Download your world folder from the server
Place it in your Bedrock client’s saves folder
Open the world settings and enable Beta APIs under Experiments
Re-upload the world to the server (replacing the existing folder)

See Enabling Experimental Features for the full upload steps.

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