Troubleshooting

This page covers the most likely mistakes when configuring Velocity Commands.

A command did not load

Check these first:

does it have type?
does it have command?
does it have enabled?
does the type-specific field exist, such as message or to_run?
is the YAML indentation correct?

If a command is invalid, the plugin skips it and logs an error.

The plugin says the `commands` section is missing

This usually means one of two things:

the file structure is wrong
there is a YAML syntax error that prevented the section from loading correctly

Start by validating your YAML and checking indentation carefully.

A `console_command` is not working

Check these points:

every entry under to-run must have executes-on, runs-on, and command
valid executes-on values are player and console
valid runs-on values are velocity and backend
console + backend is not used together are not allowed

A command says the player was not found

For message_other_player, the target player must be online on the proxy.

The plugin looks up the target by username.

A message is not colored correctly

Check settings.useLegacyColours.

if it is false, use MiniMessage tags
if it is true, use & colors

If you mix both styles carelessly, the result may not look how you expect.

A sound does not play

The command can still run successfully even if the sound fails.

Check:

the sound key spelling
the sound’s availability in your Minecraft version
whether the command was run by a player

The command usage message looks wrong

The plugin uses your command: field as the usage string.

So if the usage output looks messy, clean up the command: definition itself.

`message_other_player` seems to need an extra argument

That is expected.

The plugin internally inserts a target player argument named otherPlayer at the start of the command.

`greedy_string` command registration fails

Make sure greedy_string is the last argument in the command.

Correct: ✅


command: /mail [target:player] [message:greedy_string]

Incorrect: ❌


command: /mail [message:greedy_string] [target:player]

Final advice

When something breaks, reduce the command to the smallest working version first.

For example:


commands:
  test:
    type: "message_self"
    command: /test
    message: "<green>Working"
    enabled: true

If this loads, add complexity back one piece at a time.