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 in the plugin's config.yml is correct and reachable from the server host.
  • Check that APIKey in config.yml exactly matches apiKey in .env.
  • Ensure the port is open in your firewall if running on separate hosts.

API returns invalidToken​

The x-access-token header value does not match apiKey in .env. Update the plugin config to match.

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.

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.