Troubleshooting

Troubleshooting

This page covers common problems when using Butterfly API with Minecraft 1.21.11.

Creative Tab Shows Raw Translation Keys

If a creative tab or category displays its translation key instead of a readable name, add the missing entries to:

assets/<modid>/lang/en_us.json

Example:

{
  "itemGroup.example_mod.main": "Example Mod",
  "itemGroup.example_mod.category.materials": "Materials"
}

For more information, see Creative Tabs.

Block or Item Crashes During Construction

Minecraft 1.21.11 expects registry keys to be attached before many block and item constructors run.

Use Butterfly's keyed settings:

MOD.blockSettings("my_block");
MOD.itemSettings("my_item");

For example:

public static final Item EXAMPLE_ITEM =
        new Item(
                MOD.itemSettings("example_item")
        );

When using Butterfly API's factory-based registration helpers, these settings are normally handled automatically.

See Mod Context and Registration.

Block Item Model Is Missing

Minecraft 1.21.11 normally requires both the item definition and item model.

Check that both files exist:

assets/<modid>/items/<id>.json
assets/<modid>/models/item/<id>.json

For blocks, also check:

assets/<modid>/blockstates/<id>.json
assets/<modid>/models/block/<id>.json

See Resource Conventions.

Separate GUI or Held Model Is Missing

Items using Butterfly's separate GUI and held model system normally use:

assets/<modid>/items/<id>.json
assets/<modid>/models/item/<id>.json
assets/<modid>/models/item/<id>_held.json

Make sure the generated model identifiers match the files in your resources.

See Items.

Plush Sound Works but the Model Is Missing

Check that all of the plush resource paths use the exact same plush ID:

assets/<modid>/blockstates/<plush>.json
assets/<modid>/models/block/<plush>.json
assets/<modid>/models/item/<plush>.json
assets/<modid>/items/<plush>.json
assets/<modid>/textures/block/<plush>.png

For example, if the plush is registered as:

glow_moth_plush

all of its resource files should use:

glow_moth_plush

See Plush Resources.

Plush Has No Sound

Check that you have:

assets/<modid>/sounds.json

and the corresponding sound file:

assets/<modid>/sounds/<plush>_honk.ogg

The default plush sound ID is:

<modid>:<plush_path>_honk

If you used:

.sound(...)

on the plush definition, make sure your sound resources use the overridden sound ID instead.

See Plush API and Plush Resources.

Outlines Are Not Visible

First make sure you are using the correct outline system.

For local client-only outlines, use:

ClientOutlines.set(...);

For outlines controlled and synchronized by the logical server, use:

ServerOutlines.set(...);

See Client Outlines and Server Outlines.

Cutout or Translucent Outline Is Incorrect

For cutout or translucent renderers, try enabling model-layer matching:

OutlineStyle.builder("#FFFFFF")
        .matchModelLayer(true)
        .build();

This helps the outline mask follow the source renderer's render layer.

See Outline Styles.

Custom Renderer Does Not Produce an Outline

Custom renderers that need to contribute their own outline mask can use:

OutlineRenderers.capture(...)

Block entities whose renderer exists only for outline-mask contribution can implement:

OutlineOnlyBlockEntity

See Client Outlines.

Multiblock Pieces Vanish Immediately

Make sure every required part position can be replaced when the multiblock is placed.

The blockstate must also include the inherited multiblock properties:

FACING
PART_X
PART_Y
PART_Z

AbstractMultiblockBlock automatically adds these properties.

If your subclass overrides:

appendProperties(...)

make sure you do not accidentally remove or omit the inherited properties.

See Blocks and Multiblocks.

Multiblock Cannot Be Placed

If you are using MultiblockPlacement directly, check placement before creating the structure:

boolean canPlace =
        MultiblockPlacement.canPlace(
                world,
                origin,
                facing,
                shape,
                context
        );

Every part of the structure must have a valid replaceable location.

See Blocks and Multiblocks.

Client Helper Crashes on a Dedicated Server

MOD.client() is only available on the physical client.

Client helpers should be called from a ClientModInitializer, not from common/server initialization.

For example:

public final class ExampleClient
        implements ClientModInitializer {

    @Override
    public void onInitializeClient() {
        ExampleMod.MOD.cutout(
                ExampleMod.EXAMPLE_BLOCK
        );
    }
}

See Client Registration.

Still Having Problems?

Check the related API page for the system you are using:

• Installation
• Quick Start
• Mod Context
• Registration
• Items
• Blocks and Multiblocks
• Creative Tabs
• Plush API
• Outline API
• Math Utilities
• Resource Conventions