Troubleshooting

The bot won't start / "disallowed intents"

The login fails with a Used disallowed intents error.

Fix: enable Message Content Intent in the Discord Developer Portal → your app → Bot → Privileged Gateway Intents. The bot requests it for the chat feed and won't start without it.

Commands don't appear in Discord

You invited the bot but / shows nothing.

• Global commands take up to ~1 hour to propagate the first time. For instant registration while testing, set TEST_SERVER_GUILD_ID to your server's id — guild commands appear within a minute.
• Make sure you invited the bot with both the bot and applications.commands scopes (see Installation).
• Confirm REFRESH_SLASH_COMMAND_API_DATA=true.

"Grant required" on CFTools commands

A command replies that a grant is missing.

Fix: in CFTools, grant your application access to that server. Citadel's CFTools application must be authorized on every server it queries. Some actions (priority queue / whitelist) also need a CFTools premium plan on the server.

/server-info is empty or "unnamed"

/server-info doesn't look up by the Server API ID — it queries CFTools by game + IP + port. If SERVER_IPV4 / SERVER_PORT are wrong or left at 0.0.0.0, the lookup finds nothing.

Fix: set the server's real public IPv4 and game port (e.g. 2302) in config/servers.js. Every other CFTools command uses CFTOOLS_SERVER_API_ID and is unaffected.

/leaderboard or /player-list is empty

This is usually correct, not a bug — the server simply has no ranked players or nobody online. Verify against the CFTools dashboard. Check LEADERBOARD_BLACKLIST isn't excluding everyone.

/statistics shows no heatmap

The hit-zone heat map only renders when the player has recorded hit-zone data and STATISTICS_INCLUDE_ZONES_HEATMAP: true. A player with no PvP hits won't produce one. The renderer uses @napi-rs/canvas — no Chromium needed.

Auto-leaderboard doesn't post

• Confirm AUTO_LB_ENABLED: true and a valid AUTO_LB_CHANNEL_ID.
• The bot must be able to send messages in that channel; with AUTO_LB_REMOVE_OLD_MESSAGES: true it also needs Manage Messages.
• It posts on boot and every AUTO_LB_INTERVAL_IN_MINUTES — check the logs for a channel-resolution error.

Storefront relay isn't applying grants

• Confirm CITADEL_RELAY_ENABLED: true with a valid CITADEL_SERVICE_ID and CITADEL_API_KEY for that server.
• Check the logs for [citadel-relay] lines on boot (handshake) and on purchase.
• The buying player must have a linked Steam64, and the perk must map to a valid relay command.

Where to get help

Join the Citadel support server.