Common issues

A report that starts with "the bot is broken" usually isn't one. The causes collected here are consequences of how Discord's permission model works, and of choices your own server made, and each one has a fix you can apply yourself. This page is organised by what you can see rather than by what's causing it, because the symptom is the half you already have. Find yours below, then read the section it points at.

Find your symptom

Tell a silent bot from a refused command

These two look identical from across a channel and they have nothing in common. A refusal is a message: the bot read your command, decided against running it, and said so in an embed. Silence means no message arrived at all, and the cause is almost never the command you typed.

Start by running /help in the same channel. A slash reply comes back through the interaction rather than as an ordinary message, so it doesn't depend on the same channel permissions.

If /help answers and your prefix command doesn't, the bot can't post normally in that channel. It needs three permissions there, not two: View Channel, Send Messages, and Embed Links.

If /help answers but only in some channels, it's a per-channel overwrite. Compare a channel that works against one that doesn't in Server Settings → Channels.

If a command answers Server not whitelisted, that's not a permission problem. Your server needs access before Righteous will configure or store anything for it. See Access and the whitelist.

If nothing answers anywhere, including /help, check whether the bot is actually still in the server and shows as online. A bot that left is covered on the same page.

Read a Missing Permissions refusal correctly

The refusal names a permission. It doesn't always name who is missing it, and that ambiguity is where most of the time gets lost.

On a slash command the two cases read differently. Missing permissions: BAN_MEMBERS is about you. I'm missing permissions: BAN_MEMBERS is about the bot.

On a prefix command both cases render the same embed, headed Error using command with Missing Permissions and the permission below it. There's no wording difference to read.

So check yourself first. Run ,permissions or /permissions view on your own account. It lists your real Discord permissions and any fake ones your roles hold, in the same spelling the refusal used. If you hold the permission, the missing one is the bot's.

Two things about the bot's half are worth knowing before you go looking:

The bot's check reads its server-wide permissions, not the channel's. That's a deliberate tradeoff and it has a consequence: the bot can pass its own check and then have the real action fail because the channel denies it. If a command refuses or fails in exactly one channel, look at that channel's overwrites for the bot rather than at its roles.

Administrator on the bot settles permissions and nothing else. It grants every permission and no extra height in the role list. A bot with Administrator still can't touch a member who outranks it, which is the next section.

Not every refusal is about a permission. Some gates are something else entirely, and the slash form says which:

Give the bot a role it can act from

Discord lets a bot act on a member only when the bot's highest role sits above that member's highest role. Permissions don't change this and neither does Administrator. Righteous checks it before it tries anything, so you get a refusal rather than a half-finished punishment.

Three different messages, three different subjects. Reading the right one saves you dragging the wrong role:

The fix for the second and third is the same. Open Server Settings → Roles and drag the bot's own role higher than the roles it needs to act on.

Three rules that surprise people:

A tie counts as outranked. Equal positions are not good enough, for you or for the bot. The role has to be strictly above.

The server owner can never be actioned by the bot. Position comparisons can't express Discord's owner, so Righteous checks for them separately and refuses. That's not something a role drag fixes.

A role the bot hands out has to be below it too. This is the third message above, and the mute and jail roles are where it usually bites. If ,config muterole points at a role sitting above the bot, every mute fails, including automated ones from the filters and from protection. The same applies to roles given on join and to booster roles.

Get protection to actually fire

Anti-nuke detects through Discord's audit log. Without View Audit Log on the bot at the server level, nothing about a deletion or a permission change ever reaches it, and every rule you armed sits there doing nothing. There's no error message, because nothing was attempted.

Righteous does try to break that silence. If any anti-nuke rule is configured and the permission isn't there, the next channel or role deletion the bot sees posts an Anti-Nuke Is Not Working incident to your protection log. It fires once per server, so a log channel has to be set for you to ever see it. Set one with ,antinuke log <channel>.

The reliable move is to audit rather than wait. Run ,antinuke check. It reads your live configuration, changes nothing, and reports every reason a rule would do nothing, including this one. Run it after every change you make to protection.

Detection is only half of it. A rule can fire correctly and still appear to do nothing:

• The punishment needs its own permission on the bot. A ban rule with no Ban Members, a kick rule with no Kick Members, a timeout rule with no Moderate Members.
• mute and jail need their role set, with ,config muterole and ,config jailrole, and that role has to sit below the bot.
• stripstaff removes nothing if your staff list is empty. Add roles with ,staff add <role>.
• A whitelisted member is exempt on purpose. Check ,antinuke whitelist before assuming a rule is broken.
• warn does nothing to the member by design. It posts the incident and stops there. A rule left on warn after testing looks like a rule that isn't working.

The other three protection systems are configured separately and fail separately. Start at the Protection overview.

Use the prefix your server actually has

Every server can change its own prefix, so a prefixed example anywhere on this site is an illustration rather than a fact about your server. If a line copied out of a guide does nothing, this is the first thing to check.

Out of the box Righteous answers to three prefixes: the double comma ,,, and the two words jason and righteous. So ,,help, jason help and righteoushelp all reach the same command in a server that hasn't changed anything. Changing the symbol prefix normally leaves the two word prefixes in place, which makes them a useful way back in when nobody remembers what the symbol was changed to.

To find out for certain, run ,prefix list or /prefix list. It posts every prefix the server accepts. That needs Manage Server, so if you don't have it, ask someone who does.

To change it, ,prefix set <prefix> replaces the primary one and ,prefix reset puts the shipped defaults back. Both need Manage Server. Do it early if you're going to do it at all, because people memorise a prefix fast.

Wait out a missing or stale slash command

Discord holds the list of slash commands, not the bot. That single fact explains all three versions of this symptom.

A new command hasn't appeared, or an option still shows its old name. After the bot's command list changes, the update takes about an hour to reach every server. Give it that long before treating it as broken. Your own client caches the list too, so restart Discord once the hour is up.

The same command is listed twice in one server. A server-scoped registration is sitting on top of the global one, which happens while a command is being tested. It's harmless, both copies run the same code, and it clears itself the next time the global list updates.

A command exists but refuses. That isn't this. A refusal is a gate, so read Read a Missing Permissions refusal correctly instead.

A command has no slash form at all. Not everything does. Each command's reference page under /commands says whether a slash form exists, and says so explicitly when it doesn't.

Know what fake permissions do and what they do not

,fakepermissions add <role> <permission> lets a role use a Righteous command that would normally need a Discord permission, without giving that role the Discord permission. It's how you let a moderator role run ,ban without handing it Ban Members across your whole server. Only the server owner can configure it.

,fakepermissions type lists the names it accepts, and ,fakepermissions list shows what your server has already granted. Both prefix and slash forms of a command honour the grants, so there's no half-covered surface to worry about.

What catches people out is the word fake, which is doing more work than it looks like. The grant exists inside Righteous and nowhere else.

It changes nothing in Discord. The role's real permissions in Server Settings are untouched. Somebody with a fake Ban Members can't ban from Discord's own right-click menu, no other bot sees the grant, and nothing in Discord's interface will ever show it. ,permissions is the place it shows up, listed beside the member's real permissions.

It gives the bot nothing. Two separate permissions have to exist for a moderation command to work: yours, which a fake permission can satisfy, and the bot's own, which it can't. If Righteous doesn't hold Ban Members, ,ban fails no matter what you granted.

It doesn't lift role hierarchy. A fake permission never lets somebody act on a member who outranks them. Hierarchy is checked separately and it isn't grantable.

It isn't immunity. The message filters, the trap channel and anti-nuke treat a member holding fake permissions exactly like anybody else. Each of those systems has its own exemption list, and being staff is not one of them. Use ,filter whitelist, ,trap whitelist and ,antinuke whitelist for that, per system.

It can't open a server-owner-only door. Anti-nuke's whole configuration surface and ,fakepermissions itself are gated on being the actual server owner rather than on Administrator, and that's precisely because Administrator is something this system can hand out. Premium features aren't reachable this way either.

Repair a setting that used to work

A configuration that worked for months and then stopped has usually had something pulled out from under it. Four causes cover nearly all of it.

The role or channel it points at was deleted. Open ,config and look at the page for that feature. A setting pointing at something deleted is shown as deleted and ignored, which is the panel telling you to set it again rather than an error.

The bot's role was moved down. Any punishment that applies a role starts failing the moment the bot drops below it. See Give the bot a role it can act from.

New channels don't inherit the mute and jail overwrites. Channels created after your original setup have no idea what the muted role is, so a muted member can still talk in them. Run ,setup update to reapply the overwrites everywhere without creating anything.

Your server's access lapsed. Commands answer Server not whitelisted, or the bot has left entirely. Nothing you configured is lost, and it's all still there when access comes back. See Access and the whitelist.

Where to go next