Skip to content
Guides
My custom Discord bot won't join my server. The invite fails or it just never shows up.

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 seeLikely causeFix
Your server is missing from the listYou lack Manage Server thereGet the permission or ask the owner to invite
Error when a staff member invitesPublic Bot is offOwner invites, or turn Public Bot on
"Integration requires code grant"Requires OAuth2 Code Grant is onTurn it off on the Bot page
Commands appear, no bot in the member listInvite had no bot scopeInvite again with bot and applications.commands
Bot is in the list but greyNothing logged in, or token resetStart the program or paste the new token
Bot online, roles not givenRole hierarchyDrag 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:

  1. 1Open your app in the Developer Portal and go to Installation.
  2. 2Under Install Link, choose Discord Provided Link.
  3. 3Under Default Install Settings for Guild Install, add applications.commands and bot, then pick the bot's permissions.
  4. 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.