Why your custom Discord bot is not joining your server
Updated · VaultCord
A bot that will not join usually has one of five problems, and Discord's error messages do not always say which. Go through them in order. Most people are fixed by the first two.
Quick table
| What you see | Likely cause | Fix |
|---|---|---|
| Your server is missing from the list | You lack Manage Server there | Get the permission or ask the owner to invite |
| Error when a staff member invites | Public Bot is off | Owner invites, or turn Public Bot on |
| "Integration requires code grant" | Requires OAuth2 Code Grant is on | Turn it off on the Bot page |
| Commands appear, no bot in the member list | Invite had no bot scope | Invite again with bot and applications.commands |
| Bot is in the list but grey | Nothing logged in, or token reset | Start the program or paste the new token |
| Bot online, roles not given | Role hierarchy | Drag the bot's role above the role it gives |
1. You need Manage Server
Discord only lets a member with the Manage Server permission add a bot to a server. If you do not have it, the server never appears in the drop-down on the invite screen. Being able to see and post in the server is not enough. Ask the owner for a role with Manage Server, or send them the invite link.
2. The Public Bot switch
On the Bot page of your app in the Developer Portal there is a Public Bot toggle. When it is off, only the app owner can add the bot to servers. That is the right setting for a bot made for your own community, but it trips people up: a co-owner opens the invite and it fails. The fix is to have the account that owns the application invite it.
3. Requires OAuth2 Code Grant
The same page has Requires OAuth2 Code Grant. When it is on, the bot only joins after a full OAuth2 code grant flow, the kind a website runs on its own server. A normal invite link cannot finish that flow, so the join fails with a message about a code grant. Unless the service you use tells you to switch it on, leave it off.
4. The invite link is missing a scope
Discord only adds the bot user when the invite's scope includes bot. The applications.commands scope is what installs slash commands. For a bot in a server you want both. The simplest way to get a correct link:
- 1Open your app in the Developer Portal and go to Installation.
- 2Under Install Link, choose Discord Provided Link.
- 3Under Default Install Settings for Guild Install, add
applications.commandsandbot, then pick the bot's permissions. - 4Save, copy the link, open it, pick your server and authorize.
Close the popup or tab only after Discord says the bot was added. Closing it early is a common reason a dashboard never sees the bot arrive.
5. It joined, but it is offline
A bot in your member list with a grey dot is in the server. It is just not running. A bot is online only while a program is connected to Discord's Gateway with its token. Three things cause a grey dot:
- Nothing is running it. If you host it yourself, the program stopped or the computer is off. See free 24/7 bot hosting.
- The token was reset. Clicking Reset Token makes the old one useless. Discord closes the connection with code 4004 (authentication failed). Paste the new token wherever the bot runs. More in the bot token guide.
- A privileged intent is off. If the program asks for Server Members, Presence or Message Content and the toggle on the Bot page is off, Discord closes the connection with code 4014.
Since 10 June 2026, Discord reviews privileged intent access once an app is visible to more than 10,000 unique users. Below that you can switch the intents on yourself on the Bot page.
6. Online, but not doing its job
If the bot is green but cannot give the verified role, it is the role order. A bot can only manage roles below its highest role. Open Server Settings, Roles, and drag the bot's role (same name as the bot) above the roles it hands out. A general role called "Bots" does not count; it has to be the bot's own role. Then check channel overrides: a channel that denies Send Messages or Embed Links to that role stops the bot there.
If slash commands do not show, re-invite with both scopes from step 4, and check that the member trying them has permission to use application commands in that channel.
Questions
How do I invite a custom Discord bot to my server?
Use an invite link with the bot and applications.commands scopes, such as the Discord Provided Link on your app's Installation page, and pick the server. You need the Manage Server permission there. With VaultCord, add the server from the dashboard and it builds the invite for you.
Why is my custom Discord bot offline?
No program is logged in as the bot. Either nothing is running it, the token it uses was reset (Discord rejects it with close code 4004), or it asks for a privileged intent you have not switched on (close code 4014).
Why can't I see my server when I invite the bot?
The server list only shows servers where you have permission to add apps. Ask the owner for a role with Manage Server, or have them open the invite.
What does 'integration requires code grant' mean?
Requires OAuth2 Code Grant is switched on for your bot, so it only joins after the full OAuth2 code grant flow. A plain invite link cannot finish that. Turn it off on the Bot page unless your setup needs it.
My bot joined but cannot give roles. Why?
Its role sits below the role it should give. Drag the bot's role above that role in Server Settings, Roles, and check channel overrides.