Skip to content

Troubleshooting

Common issues and how to fix them.

Bot Not Connecting

"PLEASE SET YOUR BOT TOKEN!"

Cause: The bot token is missing or still set to the default.

Fix:

  1. Open config/AetherLink/config.json
  2. Replace "YOUR_BOT_TOKEN_HERE" with your actual bot token
  3. Restart the server

Bot is online in Discord but not responding

Possible causes:

  1. Message Content Intent not enabled
  2. Go to Discord Developer Portal
  3. Select your bot → Bot → Privileged Gateway Intents

  4. Enable Message Content Intent

  5. Wrong channel ID

  6. Verify the channel ID in config.json is correct

  7. Make sure you copied the channel ID, not the server ID

  8. Bot not in the server

  9. Re-invite the bot using the OAuth2 URL

"Channel not found or bot lacks access"

Cause: The bot cannot see the configured channel.

Fix:

  1. Check the channel ID is correct
  2. Ensure the bot has View Channel permission
  3. If the channel is in a category, check category permissions too

Messages Not Sending

Discord → Hytale not working

Check:

  1. The channel's readOnly is set to false
  2. The channel's enabled is set to true
  3. Console shows no permission errors

Hytale → Discord not working

Check:

  1. At least one channel is configured and enabled: true
  2. Bot has Send Messages permission in the channel
  3. Check console for error messages

"Missing permissions in #channel"

Cause: The bot lacks required Discord permissions.

Required permissions:

  • View Channel – See the channel
  • Send Messages – Post messages
  • Read Message History – Read past messages
  • Manage Channel – Set slowmode and channel topic (optional)

Fix:

  1. Go to Server Settings → Roles
  2. Find the bot's role
  3. Enable the required permissions
  4. Or set permissions per-channel in Channel Settings → Permissions

Commands Not Working

Possible causes:

  1. Server didn't fully start
  2. Check console for "AetherLink events registered!"

  3. If missing, there was a startup error

  4. Commands not registered

  5. This is a bug – please report it on GitHub

Cause: Reload is rate-limited to once every 5 seconds.

Fix: Wait 5 seconds and try again.

Spam Control Issues

Slowmode not being set

Cause: Bot lacks Manage Channel permission.

Fix: Grant the bot Manage Channel permission.

Messages being grouped incorrectly

The aggregation groups duplicate events within hytaleAggregateSeconds.

To disable aggregation:

"spamControl": {
  "hytaleAggregateSeconds": 0
}

Performance Issues

High CPU usage

Possible causes:

  1. Too many channels configured
  2. The bot updates topics for all channels every 60 seconds

  3. Consider disabling some channels

  4. Rapid reconnection attempts

  5. If Discord is unreachable, the bot retries with exponential backoff
  6. Check your network connection

Memory leaks

If memory usage grows over time:

  1. Check for errors in the console
  2. Restart the server periodically
  3. Report the issue on GitHub with logs

Getting Help

If your issue isn't listed here:

  1. Check the console for error messages
  2. Enable debug logging (if available)
  3. Open an issue on GitHub with:
  4. Your config.json (remove the bot token!)
  5. Relevant console logs
  6. Steps to reproduce the issue

Other information

If you are comfortable with downloading and building, if one day aetherlink doesn't work because of an hytale update you can modify and build the .jar file yourself in Build It Yourself.

Known Limitations

Limitation Reason
Max players shows "?" Hytale API doesn't expose max players yet
Death messages don't work Waiting for Hytale death event API
Advancement messages don't work Waiting for Hytale advancement API
Linking not implemented Planned for future release