Troubleshooting Guide

Common issues and how to fix them.

Installation Issues

❌ "Command Maker mod won't load"

Symptoms: Mod doesn't appear in mod list

Solution: Check these requirements:

• ✓ Fabric Loader installed correctly
• ✓ Fabric API present in mods folder
• ✓ Java 21+ installed
• ✓ Minecraft version 1.21.9+
• ✓ CMDMaker JAR in correct mods folder

Quick Fix:

1. Delete the mod from mods folder
2. Restart launcher
3. Re-download mod from Modrinth
4. Place in mods folder
5. Restart Minecraft

❌ "Failed to download Fabric API"

Solution:

• Download Fabric API manually from Modrinth
• Place JAR directly in .minecraft/mods
• Restart Minecraft

❌ Crash on startup

Check: Look at the crash log for the specific error

• java.lang.UnsupportedClassVersionError → Need Java 21+
• net.fabricmc.loader.impl.FabricLoaderImpl.load() → Fabric not installed
• Mixin errors → Corrupted mod download

Alias & Command Issues

❌ "Command doesn't work / No response"

Troubleshooting steps:

1. Check spelling of command/alias
2. Run /addcommand list to verify alias exists
3. Make sure you have permission to run the command
4. Check if the underlying command works directly
5. Run /addcommand reload to refresh

❌ "Variable not substituting / Still shows ${player}"

Causes:

• Typo in variable name (case-sensitive!)
• ${PLAYER} should be ${player}
• Custom variable not created with /setcmdvariable

Fix:

/setcmdvariable myvar "my value"
/addcommand add test say ${myvar}

❌ "Alias worked once, then stopped"

Solution: Reload the config

/addcommand reload

If still broken, check config files for errors.

❌ "Command returns weird symbols or errors"

Example output: {"text":"error"}

Cause: JSON syntax error in command

Fix: Use proper JSON escaping:

say "Use double quotes for strings"
say \'Use single quotes inside\'

Syntax Pattern Issues

❌ "Syntax pattern not matching / Not recognized"

Check:

• JSON syntax is valid (use JSONLint)
• You ran /addcommand reload after editing syntax.json
• Pattern format is correct: /tpa <player>
• Parameter names are in angle brackets

❌ "Getting parameter in wrong variable name"

Example: Pattern /tpa <player> creates wrong variable

Fix: Use correct naming: ${syntax_name_parameter}

• Syntax name: tpa
• Parameter name: player
• Variable: ${tpa_player} ✓

❌ "Multiple parameters aren't working"

Correct pattern:

/ban <player> <reason>

Correct alias:

ban-ip ${ban_player} && say Banned ${ban_player} for: ${ban_reason}

GUI Issues

❌ "/deletealiases-gui shows empty / No aliases listed"

Cause: Aliases map not synced from server

Solution:

• Run: /deletealias (without parameters) to sync
• Then run: /deletealiases-gui
• This synchronizes the client with server aliases

❌ "GUI won't open / Crashes when opening"

Check:

• Try a simple command first to ensure mod is working
• Restart Minecraft completely
• Check if you have permission to run the command

❌ "Can't delete alias from GUI"

Solution: Use command instead

/deletealias alias_name

Configuration File Issues

❌ "JSON Parse Error / Config won't load"

Common mistakes:

WRONG: { "key": "value", }  (trailing comma)
RIGHT: { "key": "value" }

WRONG: { key: "value" }  (unquoted key)
RIGHT: { "key": "value" }

WRONG: { "key": 'value' }  (single quotes)
RIGHT: { "key": "value" }

Validator: Use JSONLint to check your JSON

❌ "Aliases.json won't save changes"

Solution:

1. Completely close Minecraft
2. Edit the JSON file
3. Save and close the editor
4. Restart Minecraft
5. Run /addcommand reload

❌ "Where's the config folder?"

Location: .minecraft/config/CommandMaker/

Files:

• aliases.json
• syntax.json
• variables.json

Performance Issues

❌ "Server lagging when running alias"

Causes:

• Command is too complex
• Using selectors like @a with large player count
• Multiple chained commands

Solution: Simplify the command or split into multiple steps

❌ "Too many aliases / Mod freezes on load"

Solution: Remove unused aliases

/deletealias old_alias
/addcommand reload

Advanced Troubleshooting

❌ "Still doesn't work / I'm stuck"

Debug steps:

1. Open .minecraft/logs/latest.log
2. Search for "CommandMaker" or "error"
3. Look for red error messages
4. Note the full error text
5. Share error on GitHub issues

Test Basic Function:

1. Run: /addcommand add test say Works!
2. Run: /test
3. Should see: "Works!" in chat
4. If not → mod not loading properly

Test Variables:

1. Run: /addcommand add playertest say ${player}
2. Run: /playertest
3. Should see: your username in chat
4. If not → variable system broken

Test Syntax:

1. Create pattern /hello <name> in syntax.json
2. Create alias: hello = say Hello ${hello_name}!
3. Run: /addcommand reload
4. Run: /hello Steve
5. Should see: Hello Steve!
6. If not → syntax system broken