Skip to main content

​
FAQ & Troubleshooting

​
Setup & Permissions

This happens when Guardian’s own role is below the position it needs to manage. Discord requires a bot’s role to be higher in the hierarchy than any role it creates or assigns.Fix:
  1. Go to Server Settings → Roles
  2. Drag the Guardian Bot role to the top of the list (or at least above all roles it needs to manage)
  3. Run /guardian doctor — it will confirm the hierarchy is correct
Even with Administrator permission, Discord enforces role hierarchy for role management. Administrator does not bypass this restriction.
This is usually a channel-level permission override that’s blocking Guardian in a specific channel. Administrator grants server-wide permissions, but individual channel overrides can deny permissions even for admins.Fix:
  1. Go to the channel where Guardian is being blocked
  2. Open Channel Settings → Permissions
  3. Find Guardian’s role and remove any explicit Deny overrides
  4. Run /guardian doctor again
Guardian timed out, usually because:
  • It lacks permission to create channels or roles
  • The Discord API is slow (retry in a few minutes)
  • A name conflict exists (a role named Guardian-Quarantine already exists with wrong settings)
Fix:
  1. Delete any existing Guardian-Quarantine role and #guardian-logs channel if they exist
  2. Confirm Guardian has Administrator permission
  3. Try /setup again

​
Anti-Raid & Quarantine

Open #guardian-logs (or your configured log channel). The quarantine notification embed has a ”✅ Release Quarantine” button — click it to immediately remove the quarantine role.Alternatively, any staff member with Manage Roles can run:
/quarantine release @member
Consider pinning a message in your general channel explaining that accounts less than 24 hours old will briefly be in quarantine. This reduces confusion for legitimate new users.
Events that attract many new members (giveaways, collaborations, going viral) can trigger raid detection. To prevent this:Before the event:
/antiraid mode monitor
This keeps all detection and logging active but never auto-locks — staff are alerted but the server stays open.After the event:
/antiraid mode auto
Restore full automatic protection once the influx normalizes.
Two common causes:
  1. Role hierarchy — Guardian-Quarantine must be above your default member role so it can override channel access. If it’s below @everyone, it has no effect.
  2. Channel permission overrides — if channels explicitly grant @everyone permission to view/send, the quarantine role can’t override it.
Run /guardian doctor for an automatic diagnosis and specific fix instructions.

​
Anti-Phishing & /report

Check the following:
  1. TrustScore — you need a minimum score of 20 to submit reports. Run /trustscore @yourself to check your score.
  2. Cooldown — there’s a 10-minute cooldown between reports. Wait and try again.
  3. Already blacklisted — if the target is already in the Global Blacklist, you’ll see the existing record instead of a new report being created. This is expected behavior.
  4. No report channel configured — if /report-config set-channel was never run, reports go to #guardian-logs by default. Check that channel.
Guardian has multiple layers of anti-abuse protection:
  • TrustScore ≥ 20 — new or low-trust accounts can’t submit reports
  • 10-minute cooldown — prevents rapid-fire false reports
  • Link scan requirement — auto-bans only trigger when a link is confirmed in a phishing database, not on user accusation alone
  • Staff review — unconfirmed reports always go to staff; Guardian never auto-bans based solely on a member’s text description
A member cannot get someone banned simply by reporting them — there must be a confirmed malicious link or staff authorization.

​
Backup & Restore

If Guardian detected the channel deletion, a selective restore button was automatically posted to #guardian-logs within seconds of the deletion. Click “Restore Channels” in that embed.If the automatic restore button is no longer available (more than 60 minutes have passed):
/backup list           # Find the most recent snapshot before the deletion
/backup restore <id>   # Restore from that snapshot
Restoring a full backup will recreate channels and roles from the snapshot. Messages are not restored — only the server structure (channels, categories, roles, permissions).
You need Administrator permission to create backups. /backup list is available to anyone with Manage Guild. Check your role permissions.
Guardian does not create automatic scheduled backups — you control when snapshots are taken. We recommend:
  • After any major role/channel restructure — create a labeled snapshot
  • Before giving a new admin elevated permissions — safety net in case of compromise
  • Weekly for active communities
Free accounts have 3 backup slots. Pro accounts have unlimited storage.

​
Self-Hosting

The Docker healthcheck must authenticate with Redis. Confirm your docker-compose.yml uses:
healthcheck:
  test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]
If it still uses redis-cli ping without -a, the check will fail because requirepass is enabled. Update your compose file and restart the Redis service:
docker compose restart redis
PostgreSQL hasn’t finished initializing when the bot starts. The depends_on: condition: service_healthy in docker-compose.yml should handle this, but if you’re starting for the first time on a slow machine:
docker compose up db redis -d    # Start dependencies first
sleep 10                         # Wait for PostgreSQL to initialize
docker compose up guardian-bot -d
Docker Compose doesn’t hot-reload .env changes. Restart the affected service:
docker compose up -d --force-recreate guardian-bot

​
Still Need Help?

Discord Support Server

Join our support server for real-time help from the team and the community.

GitHub Issues

Report bugs or request features on GitHub.