Troubleshooting

Things that go wrong and how to fix them.

"Phantom can't send messages here"

The bot's role lacks Send Messages permission in that channel.

Fix: open the channel's permission overwrites in Discord → add Phantom's role → grant Send Messages.

Surfaces as missing_send_messages in Error Log.

"Role hierarchy" errors

Phantom is trying to grant or remove a role that's higher than Phantom's own highest role in the server's role list.

Fix: open Server Settings → Roles → drag Phantom's role above any role you want it to manage. A common setup is "just below your top Admin role, above everything else."

Surfaces as role_hierarchy in Error Log.

Slash commands don't appear in the picker

Three possible causes:

1. Discord hasn't propagated the commands yet. New servers can take up to an hour for commands to show. Wait, then retry.
2. Your account's role doesn't permit the command. Discord lets server admins gate slash commands per-role; check Server Settings → Integrations → Phantom → Permissions.
3. The module is disabled in Guild Settings → Modules.

Verification button doesn't grant the role

Either:

• Phantom's role is below the verified role → fix the role hierarchy.
• The verified role doesn't exist anymore → re-create it in Discord, then re-pick it in Verification settings.
• The user already has the role → they're already verified.

Welcome message doesn't post

Check:

• The welcome channel still exists and Phantom can post there.
• ignore_bots = true — and the joiner is a bot. (Common cause.)
• Module is enabled.

Error Log will tell you specifically.

Level-up announcements show "you reached level X" but X isn't changing

The level number is changing (check /plevel rank); the announcement template is showing a stale rank because of the {role} vs {rank} distinction:

• {role} = role JUST earned this level-up (empty between rungs)
• {rank} = current highest rank role (stable across level-ups within the same rung)

The seeded default {role|level {level}} shows "you reached Gold" on a rung crossing and "you reached level 7" on plain level-ups. If you customised the template to use plain {role}, between-rungs level-ups render empty.

Fix: use {role|level {level}} (with the fallback) for the right behaviour.

Phantom acts twice on the same event

Almost always: two bots running the same module. Disable one of them.

If only Phantom is running and you still see double-actions, file a bug — Phantom shouldn't act on the same event twice.

Members got auto-banned during a "raid" that wasn't actually a raid

Lower your Anti-Raid action from ban to quarantine so false positives are reversible. Tune thresholds upward (bigger window, higher threshold) if your server legitimately sees 8+ joins in 10 seconds.

For the already-banned: open the Cases page, find the auto-cases, /pmod unban each.

My Auto-Assist isn't replying

During Phantom's early access Auto-Assist is free — there's nothing to top up or maintain. If it's still not replying:

• The ticket type doesn't have Auto-Assist enabled. Open the type's settings → enable.
• The ticket type has no knowledge base uploaded. Auto-Assist defaults to escalating when it has nothing to reference.
• The user's message is being classified as needing escalation (confidence too low). Check the Phantom AI audit pane inside the ticket type's settings to see the reasoning.
• The server hit its per-server usage limit briefly. Wait a minute and try again.

Cross-Server Sync isn't propagating

Check on the subscriber server's Cross-Server Sync page:

• Is the source server set in the network?
• Are the handles bound (for automod rules that reference role/channel handles)?
• Are the relevant sync toggles on (automod sync / security sync / team roles sync)?

The Change Log at the bottom of the Cross-Server Sync page tells you exactly why a push was skipped.

The dashboard is slow

• Hard refresh (Ctrl+Shift+R) — clears your browser cache.
• Refresh dashboard button in the top bar — forces Phantom to re-fetch your session data.
• If still slow, check the status page for an incident.

Phantom got kicked from my server

You'll need to re-invite it. Open phantombot.gg/dashboard → use the Add server flow. Your previous configuration is preserved — re-adding the bot picks up where it left off.

I can't see my server in the picker

Three checks:

1. You have Discord Administrator (or own) the server. (Or a Team Role with at least one permission.)
2. Phantom is in the server.
3. The server isn't blacklisted. (Rare. If it is, you'll see a toast.)

Hit Refresh dashboard to refresh the server picker.

Where else to get help

• Discord — fastest path. Join here.
• Status page — phantombot.gg/status for known incidents.
• GitHub — file bugs at github.com/ryankny/phantom.