Troubleshooting

Concise checks for failures already documented by the CraftCord source tree. Keep credentials private while you diagnose.

RCON unreachable or authentication failing

What you will notice

Startup may log RCON unreachable: configured Minecraft server — … Commands targeting this server will fail until it is fixed. Slash commands that need RCON reply with “Could not reach the Minecraft server. Try again later.” Authentication failures are described without echoing the password.

Likely causes

• Wrong RCON_PASSWORD
• Minecraft enable-rcon is not true, or the server was not restarted after the change
• RCON_PORT does not match the RCON port in server.properties
• The bot cannot reach the RCON host from where it is running

How to check and resolve

• Confirm enable-rcon=true, matching password, and RCON port in server.properties, then restart Minecraft.
• Align RCON_HOST, RCON_PORT, and RCON_PASSWORD in your private .env.
• Keep RCON on a private network path. Do not open RCON to the public internet to “test connectivity.”
• Restart CraftCord and look for RCON ready: configured Minecraft server.

Related settings: Minecraft / RCON.

Message Content intent for the chat bridge

What you will notice

With CHAT_CHANNEL_ID set, Discord → Minecraft relay stays silent because the bot cannot read ordinary channel message bodies.

Likely causes

• Message Content Intent is off in the Discord Developer Portal
• CHAT_CHANNEL_ID is set but the bot was not restarted after enabling the intent
• The sender lacks configured-guild owner, Discord Administrator, or a configured admin/mod/member role (those messages are ignored without a reaction)

How to check and resolve

• If you want the bridge: Developer Portal → Bot → Privileged Gateway Intents → enable Message Content Intent, then restart CraftCord.
• If you do not want the bridge: leave CHAT_CHANNEL_ID blank. Slash commands and log mirroring work with default intents.
• Confirm role IDs in Roles.

Configuring MC_LOG_PATH on PebbleHost

What you will notice

Minecraft → Discord chat and events never appear when the bot cannot read latest.log.

Likely causes

• LOG_SOURCE is not local while expecting a file path
• MC_LOG_PATH points at the wrong path or is unset
• The bot and Minecraft server are on different hosts, so the log file is not on the bot filesystem

How to check and resolve

• Same machine as Minecraft: set LOG_SOURCE=local and MC_LOG_PATH=/home/container/logs/latest.log (typical PebbleHost Minecraft path documented in the README).
• Different hosts: set LOG_SOURCE=pterodactyl and the three Pterodactyl variables instead of a local path.
• Confirm the path exists in the host file manager before restarting the bot.

See Log ingestion.

Pterodactyl authentication failures

What you will notice

Logs include a message like Pterodactyl authentication failed (…). Log mirroring is disabled until the bot is restarted or credentials are fixed. Chat and events from the panel stream stop until that is corrected.

Likely causes

• Invalid or revoked client API key
• Wrong panel URL or server id
• JWT / auth rejection from the panel WebSocket

How to check and resolve

• Create a fresh client API key from the panel Account → API Credentials page and update PTERODACTYL_API_KEY.
• Set PTERODACTYL_PANEL_URL without a trailing slash and match PTERODACTYL_SERVER_ID to the id in the panel URL.
• Restart CraftCord after fixing credentials. Transient network errors retry with backoff; fatal auth errors do not keep spinning forever.
• Do not paste API keys into public issues or screenshots.

Stale global slash commands

What you will notice

Older global commands still appear in Discord clients even though CraftCord now syncs only to DISCORD_GUILD_ID. Runtime guild checks still deny unauthorized use.

Likely causes

• A previous installation registered global application commands

How to check and resolve

• Optionally clear global commands with an empty PUT to the Discord application commands endpoint, using your bot token via an environment variable — never commit the token or paste it into shell history if you can avoid it:

# Replace APPLICATION_ID; pass the bot token via an env var.
curl -X PUT "https://discord.com/api/v10/applications/APPLICATION_ID/commands" \
  -H "Authorization: Bot $DISCORD_TOKEN" \
  -H "Content-Type: application/json" \
  -d "[]"

• Restart the bot or run /sync in the configured guild so guild commands are re-registered.
• Do not wipe Discord data, regenerate tokens, or force unrelated resets as a first step.

More setup context: Getting started and Configuration.