Fix common Aegis issues
Start with /diagnostics for a server health report, then use the matching guide below. Most problems come down to permissions, role hierarchy, or a missing channel configuration.
Commands & connection
Commands are missing or appear twice
Confirm the bot was invited with the applications.commands scope. Global commands can take up to an hour to propagate. For instant development updates, set DISCORD_TEST_GUILD_ID; clear former test guild registrations with DISCORD_CLEAR_GUILD_IDS.
The bot will not start
Verify DISCORD_TOKEN, DISCORD_APPLICATION_ID, and MONGO_URI are present and valid. A MongoDB connection failure is commonly caused by an Atlas IP allow-list, paused cluster, or unescaped password characters.
/diagnostics inside your server for a live check of Aegis permissions, logging, welcome settings, role setup, and AutoMod.Moderation & AutoMod
Ban, timeout, role panel, or auto-role says “Missing Permissions”
Move the Aegis role above the target member or role in Server Settings → Roles. The bot cannot act on equal or higher roles, even when it has the correct Discord permission. The moderator running a moderation command must also be above the target.
AutoMod does not catch messages
Run /automod status to confirm the rule is enabled. Then check the blocked-word list and exemptions with /automod exempt list. Aegis also needs View Channel and Manage Messages in the affected channel for deletion actions.
Suggestion votes or panels are not updating
Confirm the bot has View Channel, Read Message History, and Send Messages in that channel. Recreate a deleted or stale panel with its setup command; Aegis intentionally refuses controls that are no longer backed by a stored configuration.
Tickets, reminders & welcome flows
A ticket cannot be created or managed
Check that Aegis has Manage Channels and its role is high enough to apply channel overwrites. Only ticket owners can close their own ticket; access changes, claims, and transcripts are reserved for configured support staff or channel managers.
A reminder, scheduled message, or giveaway did not fire
Confirm the target channel still exists and Aegis can send messages there. Pending tasks and active giveaways restore after restarts; overdue tasks run on the next successful startup. If delivery fails repeatedly, recreate the task in a valid channel.
Welcome messages or auto-roles do not work
Enable Server Members Intent in the Discord Developer Portal. Then confirm the welcome channel grants View Channel and Send Messages, and place Aegis above the configured welcome role with Manage Roles enabled.
Website & deployment
Status is degraded or metrics are zero
During startup, the bot may still be connecting to MongoDB or Discord. Wait briefly and refresh Service Status. A zero guild count can also mean the bot has not joined a server yet.
The website looks stale after deployment
HTML routes are served with revalidation-friendly headers while versioned assets are cached for performance. If a reverse proxy sits in front of Aegis, ensure it does not cache HTML pages indefinitely.
Fly.io repeatedly restarts the service
Inspect deployment logs for missing secrets, MongoDB connection errors, or memory pressure. Verify the Discord token and Mongo URI secrets, Atlas network access, and that the VM has sufficient memory for the bot workload.
Still stuck?
- Run
/diagnosticsand save the relevant warning text. - Check the console or deployment logs with
LOG_LEVEL=debugtemporarily enabled. - Record the command used, exact error, server channel, and reproducible steps before contacting support.
Need the command syntax?
Browse the complete slash-command reference or check live service health before escalating.