Diagnostic Codes
When a menu loads or /menu reload runs and the configuration has a problem, the server console prints a log line like this:
[shop] menu-items[0].material (diamond) unknown or non-item material: DIMAOND [unknown-material]
The text in the trailing [ ] is the diagnostic code. Codes are stable identifiers that stay the same even when the message wording changes.
See Reload & Validation for how to read the log.
Severity
| Severity | Meaning |
|---|---|
| ERROR | The reload candidate (or the menu) is rejected. The previous configuration stays in use. A fix is required. |
| WARNING | Only the offending part is dropped, or a default is used, and loading continues. Output can be silenced with diagnostics.log-warnings-on-load: false. |
The same code can be an ERROR for one cause and a WARNING for another. Check the "Severity" column below.
General Input Mistakes
| Code | Severity | Cause | How to fix |
|---|---|---|---|
invalid-type | ERROR | A key's value has the wrong type: menu-items is not a list, a text value is a number or list, and so on. | Match the YAML to the message (must be a list / must be text / must be a number / must be true or false / must be a section). |
invalid-value | ERROR | A value is outside the allowed range or choices: a misspelled click-policy, an executor other than player / console, a delay duration of 0 or less, negative title ticks, an unknown body type, a type: input command without {variable-name}, and so on. | Fix the value as the message says. In a type: input command, include {input} (or the name you set with variable). |
missing-field | ERROR | A required key is missing: an item without command / action / actions, an action without type / menu / message / sound / prompt / world / x / y / z / effect, no open-command.name, an inputs entry without id, a cooldown without duration, no material, and so on. | Add the missing key. For a purely decorative item, write actions: []. |
Items and Placement
| Code | Severity | Cause | How to fix |
|---|---|---|---|
unknown-material | ERROR / WARNING | An item's material does not exist or is not an item (ERROR). A menu-background-item material is unknown (WARNING; the default GRAY_STAINED_GLASS_PANE is used and loading continues). | Correct the material name (for example DIAMOND). Use none for no background. |
invalid-slot | ERROR | slot is outside 0 to menu-size - 1, or location is not in column,row form, not numeric, or out of range. | Keep slot in range. Write location as "column,row" (column 1-9, row 1 to menu-size / 9). |
duplicate-slot | ERROR | Several items use the same slot. | Change one of the slots. |
duplicate-element-id | ERROR | Several items have the same id (including automatically derived ones). | Make each id unique. |
slot-overrides-location | WARNING | One item has both slot and location. slot wins. | Keep only one. |
invalid-size | ERROR | menu-size (or presentation.inventory.size) is not a multiple of 9 between 9 and 54. | Use one of 9, 18, 27, 36, 45, 54. |
unknown-component | WARNING | components has an unknown key. It is ignored. | Use the supported keys (unbreakable, max-stack-size, damage, max-damage, repair-cost, rarity, item-model, hide-tooltip, enchantment-glint-override). |
Actions
| Code | Severity | Cause | How to fix |
|---|---|---|---|
ambiguous-action | ERROR | action and actions are both written. | Keep only one. |
action-overrides-command | WARNING | command and action / actions are both written. command is ignored. | Remove the one you do not need. |
unknown-action-type | ERROR | The action type is unknown. | Supported types: command, player-command, console-command, open-menu, close-menu, message, sound, title, teleport, delay, potion-effect, input. |
empty-command | ERROR | The command is empty (blank, or only /). | Write a command. |
no-usable-action | ERROR | action or actions was written but no valid action remained. | Fix the individual errors first. |
unknown-sound | WARNING | The sound name does not exist. Only that sound is dropped and the menu still opens. | Correct the sound name (for example ENTITY_PLAYER_LEVELUP). |
unknown-menu-reference | ERROR | An open-menu (or sub_<id>) target names a menu ID that does not exist. Variants and the actions that run after a type: input are checked too. | Fix the menu ID or create the matching sub/<id>.yml. |
Conditions and Variants
| Code | Severity | Cause | How to fix |
|---|---|---|---|
invalid-condition | ERROR | A condition is malformed: an unknown key, an empty permission, world without in / not-in, an empty gamemode, a placeholder missing value / operator / compare, an unknown operator, an all / any that is not a list, and so on. | See Conditions and the Condition List. |
invalid-variant | ERROR | A variant has no override section. | Add override:. |
Presentation, Inputs, Cooldowns and Commands
| Code | Severity | Cause | How to fix |
|---|---|---|---|
invalid-presentation | ERROR / WARNING | The presentation mode name is unknown (ERROR; presentation.mode or runtime.default-presentation). native.columns / native.button-width is below 1 (WARNING; the default is used and loading continues). | Pick a mode from inventory, native-preferred, native-required, rich-preferred, rich-required, auto. |
dialog-key-ignored | WARNING | dialog and presentation are both written. dialog is ignored. | Keep only one. |
invalid-cooldown | ERROR | The cooldown duration is invalid (0 or less, not a number), or the value is neither a duration nor a section. | Write a positive duration such as 5s. |
invalid-input | ERROR / WARNING | An inputs definition has a problem. An unknown type, min above max, max-length or timeout-seconds of 0 or less, an option with no options or duplicate option ids, an initial the input rejects (ERROR). min / max on a non-numeric type, options on a non-option input, a type: input action with nothing to run afterwards (WARNING). | Fix it as the message says. |
duplicate-input-id | ERROR | Two inputs in one menu share an id. | Make each id unique. |
unknown-input-reference | ERROR | An item's input-refs names an input id that was not declared. | Declare it in inputs, or fix input-refs. |
invalid-open-command | ERROR | open-command name or aliases contains disallowed characters or exceeds 32 characters. | Use only letters, digits, _ and -, up to 32 characters. |
Errors Outside the Menu YAML
These errors have no diagnostic code and appear in the reload log in a different form.
| Message | Cause | How to fix |
|---|---|---|
Command '/xxx' is requested by both 'a' and 'b' | open-command in several menus uses the same command name. | Change the name or aliases. |
Command '/xxx' is already owned by <plugin> | Another plugin already owns a command with that name. | Change open-command.name or aliases. |
Duplicate menu ID: xxx | Two YAML files with the same name sit in different folders. Menu IDs come from the file name and cannot repeat. | Rename a file. |
Menu file not found / Configuration file is empty | main.yml is missing or empty. | Restore the file. |
Candidate config.yml is invalid | config.yml is not readable YAML. | Fix the syntax (indentation, quotes, and so on). |