Troubleshooting

Troubleshooting

Ordered roughly by how often each one is the actual cause.

A role-related feature silently does nothing

Check role hierarchy first. Discord will not let a bot grant, remove or moderate anyone whose highest role sits above the bot's own — regardless of which permissions you granted. This affects the captcha, role menus and the honeypot.

Fix: Server Settings → Roles → drag PariahBot above every role it needs to act on.

/security captcha setup checks this up front and refuses with an explanation. The others fail at the moment of use, which is why this is the first thing to check.

Commands don't appear in a server

Work through these in order:

1. Did you register them? npm run deploy after any command change.
2. Is GUILD_ID set? If it's set, commands register to that one server only. Blank it to register globally. See Configuration.
3. Global commands can take up to an hour to propagate. They're often faster, but a brand-new global registration genuinely may not appear immediately. This is Discord-side; nothing to fix.
4. Was the bot invited with the applications.commands scope? Without it, the bot joins but can't register commands. Re-invite using the link in Bot Setup.

Commands appear, but the bot isn't in the server

The commands show in the picker, but the bot isn't in the member list and nothing answers. The app was added with only the applications.commands scope, which lets it add commands without the bot itself joining. The usual cause is the Install Link on the Developer Portal's Installation page, whose default Guild Install scope is just applications.commands. Re-invite using the link in Bot Setup, which has both bot and applications.commands. To fix the Install Link too, add bot to its Guild Install scopes, with permissions.

Commands appear twice

You registered globally while guild-scoped registrations still existed. Both sets show up. Clear the guild-scoped ones — see the snippet in Configuration.

"This is for admins" / "This is for staff"

Working as intended. Staff come in two levels (see Server-Roles):

• "This is for admins": the command is admin-only (/setup, /security, /mod config and remove-case, /bannedwords on/off and lists). It needs Discord's Administrator permission or an admin role (/setup admin-role add). A mod role isn't enough.
• "This is for staff": it needs a mod role, an admin role or Administrator.

Manage Channels is deliberately not enough for either.

Locked out? If no admin roles are set, only Administrators can run /setup. An Administrator has to run /setup admin-role add role:@YourRole. Mod roles used to count as admin before admin roles existed, which is why a server that only set mod roles now sees "This is for admins".

/security captcha setup refuses to run

No member role is set, so the captcha would have no role to grant.

The captcha's whole job is handing out the member role, so it won't configure without one:

/setup member-role role:@Members

Or create it inline: /setup member-role name:Members color:#3498db.

The verification button does nothing / says the check expired

Pending challenges are held in memory, so restarting the bot forgets them. The member just presses Start verification again for a fresh one. Challenges also expire after 5 minutes.

If it consistently fails after picking the right option, that's role hierarchy — see the top of this page.

Honeypot didn't remove someone

• Are they staff, an admin or a mod? Those are always skipped, by design.
• Does the bot have Ban Members? Required even for the default "remove", because that's implemented as a softban (ban then immediate unban, so Discord purges their recent messages).
• Is the target above the bot in the role list? Same hierarchy rule.

Check /alerts status too — failures are reported through the alert system, so if alerts aren't configured you won't see the error.

Auto-delete isn't deleting

• Pinned messages are never deleted. That's deliberate.
• Does the bot have Manage Messages in that channel, and Read Message History to see the backlog?
• /autodelete status confirms the channel is actually configured.
• Time-based deletion runs on a sweep every 60 seconds, so expiry isn't instant.

The admin dashboard won't load or sign in

See the troubleshooting table on Admin-Dashboard. The usual causes:

• the SSH tunnel isn't open
• the redirect URL isn't registered exactly (port included)
• the client secret was reset
• you're signed in to Discord with an account that doesn't own the bot

The startup log (journalctl -u pariahbot.service) says whether the dashboard is listening, and if not, why.

RSS feed items don't post

1. Nothing yet? Only items published after the feed was added are posted. Run /rss test to check the channel works.
2. /rss list shows Couldn't read the feed. The site was down, moved, or blocks bots. Open the address in a browser. The bot keeps trying every 10 minutes.
3. /rss list shows Couldn't post. The channel was deleted or the bot can't post there. Remove the feed and add it again.
4. "…is on a private or local network". By design, the bot never fetches addresses on its host's own network. See RSS-Feeds.

/mod refuses to act on someone

The reply always says which check failed:

• "…is staff": by design, the bot never acts on its own admins or mods. Take their role away first.
• "Your highest role isn't above…": you can only act on people below you, as with Discord's own kick and ban.
• "My highest role isn't above…": drag PariahBot above their highest role in Server Settings → Roles.
• "I need the … permission": add it to the PariahBot role. Bots invited with the Required-only link before /mod existed lack Kick Members and Timeout Members.

The right-click Kick member, Ban member and Timeout member actions missing? Refresh Discord with Ctrl+R. See Moderation.

Temporary voice channels misbehave

1. Joining a hub does nothing. The bot needs Manage Channels and Move Members, and to be able to see the hub's category.
2. /vc says "Run this in #channel's own chat". Run it from the text box inside your voice channel.
3. /vc says admins turned that control off. See /voice list, and /voice owner-control to turn it back on.
4. A new channel ignores a hub change. Hub settings apply to channels created afterwards.

The full table is on Temp-Voice-Channels.

Banned words aren't blocked, or blocks aren't reported

1. "I need the Manage Server permission." Add Manage Server to the bot's PariahBot role in Server Settings → Roles. Bots invited before banned words existed don't have it.
2. It's off. /bannedwords status shows Off. Run /bannedwords enable.
3. The sender is exempt. Discord never blocks members with Administrator or Manage Server, so test with a regular account. Also check Server Settings → AutoMod for exempt roles or channels on the PariahBot: banned words rules.
4. The word didn't match. Matching is whole-word: cat doesn't block "category". Use cat* or *cat*.
5. "The maximum number of rules was reached." The server already has six AutoMod keyword rules. Delete one you don't need in Server Settings → AutoMod, then /bannedwords enable again.
6. Blocked, but not reported. Blocks go to the admin alerts. Check /alerts status. A message blocked by an AutoMod rule the bot didn't create is never reported by the bot.

Stream or upload alerts don't post

Work through these in order:

1. "Twitch/YouTube isn't set up on this bot's host yet." The credentials aren't in hom.env, or the bot hasn't been restarted since you added them. It only reads hom.env at startup. Run sudo systemctl restart pariahbot.service, then confirm the startup log no longer says … alerts are disabled.
2. No alert channel. /streamers list shows Alert channel: Not set. Run /streamers channel.
3. A self-linked streamer lost the streamer role. Self-links only alert while the member holds it, checked on every alert. Give the role back, or have an admin /streamers add them so it isn't needed.
4. It was posted before the channel was added. Only new uploads and streams are announced. Wait for the next one.
5. YouTube is just slow. Feeds refresh every few minutes and the bot checks every 2, so 2–10 minutes is normal. Twitch is about a minute.
6. A YouTube 24/7 or long-running stream. These are found through the channel's /live page, which is checked every 15 minutes, so give it that long. A 24/7 stream is only announced once, the first time it's seen, so it won't post again later. If one never appears, YouTube may have changed that page. See Known gaps on Streamer-Alerts.
7. YouTube quota ran out. The log shows YouTube refused the request (HTTP 403). Alerts resume after midnight Pacific. Check usage in Google Cloud under APIs & Services → YouTube Data API v3 → Quotas.
8. Twitch credentials rejected. The log shows Twitch rejected the client credentials. Check both values, and that the Twitch app is Confidential.

The ping arrives without notifying anyone? The ping role isn't mentionable. Enable Allow anyone to @mention this role, or give the bot Mention Everyone.

Instagram posts don't appear

Work through these in order:

1. "Instagram isn't set up on this bot's host yet." INSTAGRAM_ACCESS_TOKEN or INSTAGRAM_BUSINESS_ACCOUNT_ID is missing from hom.env, or the bot hasn't been restarted since. Restart it, and check the startup log no longer says Instagram alerts are disabled.
2. No channel. /instagram list shows Channel: Not set. Run /instagram channel.
3. It was posted before the account was added, or more than 7 days ago. Only newer posts are shared.
4. It's slow, not broken. The bot checks every 10 minutes.
5. It's a story. Stories aren't available through the API.
6. The log says Instagram says the access token is missing a permission. The token or the System User is missing something. Check the five permissions and the assigned Page and Instagram account, then generate a new token. See Check the token works on Instagram-Alerts.
7. The log says Instagram refused the access token. It was revoked, for example from the System User or by removing the app. Generate a new one.
8. The log says @name now belongs to a different account. The account renamed and someone else took the name. /instagram remove it, then /instagram add its new username.

/instagram add says it couldn't read an account? Check the spelling. If it's right, the account is personal, private or age-gated. Only public Business or Creator accounts can be followed.

The bot isn't picking up new code

If the auto-update job is installed, it only acts when the tracked branch actually moves — and it tracks one specific branch, main unless someone changed it. If you merged to a different branch, nothing happens. Check, as the bot user:

crontab -l                                      # is the pariahbot-sync line there?
grep '^BRANCH=' /usr/local/sbin/pariahbot-sync  # which branch is it watching?
tail -50 /opt/PariahBot/sync.log

No pariahbot-sync line means the job was never installed, or was turned off: see Host Installation → Auto-update job to turn it on.

A repeated fatal: couldn't find remote ref <branch> in that log means the tracked branch was deleted (e.g. after its PR merged) — point the job at main. See Host Installation.

To force a sync now, as the bot user:

/usr/local/sbin/pariahbot-sync

In the container install, there's no git sync: see Container Installation → Updates. update.log in /opt/pariahbot-container records each update and any failed pull.

The server log posts nothing

Run /logging status. It lists each section, its channel, and anything stopping it, worded as the fix. The usual causes:

• The section is off, or has no channel. /logging set picks one and switches it on.
• The bot can't post there. It needs View Channel, Send Messages and Embed Links in the log channel.
• Kicks and bans, or Server changes, are silent. The bot needs View Audit Log on its role.
• The whole feature is switched off. Check /setup feature list.
• Server changes made by the bot itself (temporary voice channels, role menus) are left out on purpose.
• Edits and deletions show no text. The bot's host hasn't switched on message text, or the message is older than a day or from before the bot last restarted.

Full guide: Server-Log.

The bot won't start

sudo journalctl -u pariahbot.service -n 50     # systemd install
sudo docker logs pariahbot 2>&1 | tail -50     # container install

Common causes:

• An invalid token was provided — DISCORD_TOKEN is wrong, or was reset in the Developer Portal.
• Discord refused to connect: the bot asked for a privileged intent — switch on Server Members Intent in the Developer Portal (your application → Bot → Privileged Gateway Intents), and Message Content Intent too if SERVER_LOG_MESSAGE_CONTENT is on. Then restart. Every install needs Server Members since the Server-Log arrived; see Bot-Setup.
• NODE_MODULE_VERSION mismatch on better-sqlite3 — native module built against a different Node version. Re-run npm ci --omit=dev under Node 24. Note the sync job uses the bot user's nvm, so running it as root can produce this.
• A SqliteError on startup — the schema migrates itself on boot, so this usually means a hand-edited database. The DB is a single file at data/pariahbot.sqlite.

Where to look

sudo journalctl -u pariahbot.service -f     # the bot itself
tail -f /opt/PariahBot/logs/commands.log    # who ran what, and whether it failed
tail -f /opt/PariahBot/sync.log             # auto-update job

In the container install:

sudo docker logs -f pariahbot                          # the bot itself
sudo docker exec pariahbot tail -f logs/commands.log   # who ran what
tail -f /opt/pariahbot-container/update.log            # update job