Skip to main content

Troubleshooting

Common issues and how to resolve them. Enable debug mode first when something goes wrong - it significantly increases log verbosity across API calls, Discord events, and cron jobs.

General​

Enable Debug Mode​

Set debug: true in config.json to enable verbose logging:

{
  "debug": true
}

This logs additional detail for API calls, Discord events, and cron jobs.

API Connection Issues​

Plugin reports "Connection refused" or API errors​

  • Confirm zander-web is running and accessible from the Minecraft server.
  • Verify BaseAPIURL (or, for zander-pgm, api.baseUrl) in the plugin's config.yml is correct and reachable from the server host.
  • Check that the plugin's API key exactly matches apiKey in .env.
  • Ensure the port is open in your firewall if running on separate hosts.
warning

zander-velocity (and, by structural parity, likely zander-waterfall) polls a heartbeat endpoint every 60 seconds and disconnects every connected player if the check fails. A misconfigured BaseAPIURL or an unreachable zander-web instance will actively kick your whole proxy's playerbase, not just silently degrade - treat proxy-to-web connectivity as critical-path in production.

API returns invalidToken​

The x-access-token header value does not match apiKey in .env. Update the plugin config to match. Note zander-pgm uses a different scheme - it sends Authorization: Bearer <api.token> instead of x-access-token, so if only Mixed/PGM ingestion is failing, check api.token in zander-pgm's config.yml specifically.

API returns feature-disabled error​

The feature is turned off in features.json. Enable it by setting the relevant key to true.

Discord Bot Issues​

Bot does not respond to commands​

  • Confirm the bot token (discordAPIKey) is correct and the bot is online.
  • Verify the bot has been re-invited if you've changed its permissions.
  • Check that discord.guildId in config.json matches your Discord server ID.
  • Ensure the required privileged gateway intents are enabled in the Discord Developer Portal (Message Content, Server Members, Presence).

Slash commands not appearing​

Discord can take up to an hour to propagate new slash commands globally. Check the console output on startup for command registration errors.

Discord punishments not working​

  • Confirm the issuing user's Minecraft account is linked to their Discord account.
  • Verify the user has the required LuckPerms permission node (e.g. zander.discord.punish.warn).
  • Check that the muted role ID in config.json is correct.

Database Issues​

prisma generate fails​

Ensure DATABASE_URL in .env is correctly formatted and the database is accessible:

mysql://user:password@127.0.0.1:3306/zander

Migrations fail​

  • Run migrations in numeric order from the migration/ directory.
  • Check for existing conflicting schema by reviewing the error output.
  • For prisma migrate deploy failures, check that the _prisma_migrations table is not in an inconsistent state.

LuckPerms rank data not loading​

  • Confirm LUCKPERMS_URL points to the correct LuckPerms database.
  • The LuckPerms database user needs SELECT permission on the LuckPerms tables.

Hub /fly permission not working as expected​

zander-hub's plugin.yml declares the /fly permission as zander.fly, but the command code (commands/fly.java) actually checks zander.hub.fly - and Bukkit does not force the two to match, so zander.fly is a dead node that nothing reads. If a player can't fly, grant them zander.hub.fly (not zander.fly, which has no effect). See Permissions for details.

Web Issues​

Session not persisting (users logged out on refresh)​

  • Ensure sessionCookieSecret is set and consistent - changing this value invalidates all existing sessions.
  • Check that the session database table exists (created by dbinit.sql).

Push notifications not working​

  • Ensure VAPID_SUBJECT, VAPID_PUBLIC_KEY, and VAPID_PRIVATE_KEY are all set in .env.
  • VAPID keys must be generated as a pair using web-push generate-vapid-keys.

Creator content not appearing on Watch page​

  • Ensure the user has zander.watch.creator in LuckPerms.
  • Confirm the user has linked their Twitch or YouTube account in their profile.
  • Verify content matches the configured filter (title markers, tags, or description markers in config.json).
  • Check that Twitch/YouTube OAuth credentials are set in .env.

Logs​

System activity is logged to the database and viewable in the dashboard under Dashboard → Logs (requires zander.web.logs permission). Each log entry includes the user, feature, log type (success/warning/error), description, and timestamp.