Troubleshooting

Troubleshooting

The client disconnects immediately

• Check that the server runs with online-mode=false — MBC is an offline-mode client
• Check server_address and the port (host:port, or a bare SRV domain)
• Look at the console output; the client prints the server's disconnect reason

"Connection failed" on startup

• The server may be down or the address wrong
• A firewall or restricted network may block the connection
• Set fast_start: true to skip the remote version check when the network blocks the status endpoints

My antivirus flags the executable

PyInstaller single-file executables unpack themselves at runtime, which heuristic scanners commonly flag — this is a false positive. Whitelist the folder, or run from source with python main.py.

On macOS, Gatekeeper blocks unsigned binaries: right-click the file and choose Open, or run

xattr -d com.apple.quarantine ./MinecraftBotClient-en

Permission denied on macOS / Linux

Make the binary executable once:

chmod +x MinecraftBotClient-en

The config file is ignored

config.json (or config.en.json / config.zh.json) must sit in the same folder as the binary. When the file is missing it is created with defaults; when it is corrupt it is renamed to config.json.corrupt and defaults are regenerated.

Autocomplete or history does not work

Interactive input needs a real terminal (TTY). Piping output or running through a non-interactive shell falls back to plain line input. On Windows use the standard console; on macOS/Linux run the client directly in Terminal or your terminal emulator.

Bots do not register or log in (multi-bot mode)

• bot_auth_enabled must be true and bot_auth_password must not be empty
• Raise bot_auth_delay — some servers need a moment after the join before commands are accepted
• Check the command templates; {password} is replaced with your password, for example /register {password} {password}
• Some login plugins expect different commands — set bot_auth_register_command and bot_auth_login_command to match

Too many bots, server kicks everyone

Raise bot_join_delay (for example to 1.0) so the joins are spread out.

Where are the log files?

In a log/ folder beside the binary. Each session creates a timestamped file such as MBC-2026-09-04_22-55-29.log while logging is enabled.

Still stuck?

Open an issue: https://github.com/creaddinscart/MinecraftBotClient/issues