FAQ and Troubleshooting

FAQ & Troubleshooting

The plugin does not load on 1.21.x: "Unsupported API version 26.3"

Version 1.6 declared api-version: '26.3', which is a minimum, so 1.21.x servers rejected it. Use 1.6.1, which declares api-version: '1.21'.

The plugin does not load on 1.20.x or older

That is expected. This build declares api-version: '1.21', and older servers reject it. A separate legacy build for 1.16.5–1.20.x is planned. Keep using an older release on those versions for now.

Hex colors appear as raw text

Check these points:

1. legacy-color-support: false in config.yml.
2. Correct syntax: &#FF5555 or <#FF5555>.
3. The client supports hex colors (1.16+; every Minecraft version supported by this build does).
4. Run /cdm reload after editing.

Inside messages.yml, YAML may need quotes around strings starting with special characters:

death-title: "<#FF5555>YOU DIED"

My changes do nothing after editing the files

Run /cdm reload. If validation finds errors, the reload is aborted and the old configuration stays active unless ignore-validation-errors: true.

1. Check the console for the validation report.
2. Run /cdm config validate.
3. Fix the reported sounds, particles, modes or conditions.

A custom message for a damage cause is not used

• The cause must match a Bukkit DamageCause name: FALL, FIRE, ENTITY_ATTACK, PROJECTILE...
• Check the group: vip and admin messages only apply with use-permission-based-messages: true and the matching permission.
• Check conditional-messages: a matching condition or a default entry can override cause-messages.
• Check per-world-messages: a world override takes priority over everything.

VIP or Admin messages never appear

1. Set use-permission-based-messages: true in config.yml.
2. Give the player cdm.message.vip or cdm.message.admin (admin wins over vip).
3. Run /cdm reload.

Console warning: "No message found for world/group/cause. Using default."

No message matched for that world, group and cause, so the plugin used &c{victim} has died. Add the cause to cause-messages, or add a default-messages entry for the group.

PlaceholderAPI placeholders are not replaced

• Install PlaceholderAPI.
• Install the expansion that provides the placeholder (for example Vault or Player).
• PlaceholderAPI is optional and detected at runtime; check the console for a detection message.
• PlaceholderAPI placeholders use %percentages%; built-in placeholders use {braces}.

Vault economy is not charging players

1. Install Vault and an economy plugin.
2. Set cost-per-death-message above 0.0.
3. Make sure the player's group is not listed in exempt-groups-from-cost.
4. The player needs enough balance; otherwise the custom message is skipped.

"Invalid sound" or "Invalid particle" warnings

The configured name does not exist on the server. Run /cdm config validate, use a valid value, and reload. Invalid values fall back to the defaults (entity.player.death and EXPLOSION).

Sounds accept entity.player.death or ENTITY_PLAYER_DEATH. Particles use names such as EXPLOSION, EXPLOSION_EMITTER or CLOUD.

Where are the configuration files?

plugins/CustomDeathMessages/config.yml
plugins/CustomDeathMessages/messages.yml

They are created on first start and are never overwritten by updates.

Can I create additional message groups?

No. Three groups are built in: default, vip and admin. For more variety, use conditional messages, per-world messages or different cause entries.

How do I stop a player from receiving custom death messages?

Give them the permission cdm.bypass.

How do I preview messages without dying?

/cdm test FALL
/cdm test ENTITY_ATTACK Steve Diamond_Sword

The command prints a summary with the final message, broadcast mode, sound, particle and cost.

How do I disable messages to the whole world?

message-to-victim: true
message-to-world: false
message-to-radius: 0

The victim still sees the message; nobody else does.

Update notifications

Players with cdm.admin (or OPs) receive a chat notice on join when a newer version is published. The console also logs the notice. The check uses the public Modrinth API.