> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyzecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Common errors when hosting a Discord bot

> Common errors when hosting a Discord bot and how to fix them: Used disallowed intents, TokenInvalid, Missing Permissions, Cannot find module and more.

Each section below starts with the exact message you see in the log. On Hyze Cloud, logs are in the app under **Observability → Console**. If the deploy failed before the bot started, check the **Deployments** tab.

## Used disallowed intents (discord.js)

```text theme={"system"}
Error: Used disallowed intents
```

In older discord.js versions, the same failure shows up as `Privileged intent provided is not enabled or whitelisted`.

**Cause.** Your code requests a privileged intent that is turned off in the Developer Portal. There are three privileged intents: `GuildMembers`, `GuildPresences` and `MessageContent`.

**Fix.**

1. Open the [Discord Developer Portal](https://discord.com/developers/applications), pick your bot and go to **Bot**.
2. Under **Privileged Gateway Intents**, turn on the intents your code requests: **Server Members Intent**, **Presence Intent** or **Message Content Intent**.
3. Save and restart the bot.

If the bot does not use one of those intents, remove it from the `intents` list in `new Client(...)`.

## TokenInvalid: An invalid token was provided (discord.js)

```text theme={"system"}
Error [TokenInvalid]: An invalid token was provided.
```

**Cause.** `client.login()` received a wrong or empty token. On a host, the most common reason is a missing environment variable: `process.env.DISCORD_TOKEN` arrives as `undefined`.

**Fix.**

* Check that the `DISCORD_TOKEN` variable exists in the app, with that exact name. On Hyze: **Settings → Environment variables**.
* Check that the code reads the same name: `client.login(process.env.DISCORD_TOKEN)`.
* Paste the token without quotes and without leading or trailing spaces.
* If you generated a new token in the portal, the old one no longer works. Update the variable.
* After changing the variable, restart the app. Environment variables are read when the process starts.

## PrivilegedIntentsRequired (discord.py)

```text theme={"system"}
discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting privileged intents that have not been explicitly enabled in the developer portal.
```

**Cause.** Same problem as `Used disallowed intents`: the code turns on `intents.members`, `intents.presences` or `intents.message_content`, but the intent is off in the Developer Portal.

**Fix.** In the portal, under **Bot → Privileged Gateway Intents**, turn on the intents your code uses and restart the bot. If the bot does not need one of them, set it to `False` in your code.

## LoginFailure: Improper token has been passed (discord.py)

```text theme={"system"}
discord.errors.LoginFailure: Improper token has been passed.
```

**Cause.** The token passed to `client.run()` is wrong, was reset in the portal or has extra spaces or quotes. If the variable does not exist at all, the error changes: `os.environ["DISCORD_TOKEN"]` raises `KeyError`, and `os.getenv("DISCORD_TOKEN")` returns `None`, which discord.py rejects.

**Fix.**

* Copy the token again under **Bot → Reset Token** in the Developer Portal.
* Store it as `DISCORD_TOKEN` in the app's environment variables, without quotes.
* Read it with `os.environ["DISCORD_TOKEN"]`. If it is missing, the log names the variable right away.
* Restart the app after changing the variable.

## Missing Access and Missing Permissions

```text theme={"system"}
DiscordAPIError[50001]: Missing Access
DiscordAPIError[50013]: Missing Permissions
```

In discord.py, the same errors show up as `discord.errors.Forbidden: 403 Forbidden (error code: 50001): Missing Access` and `(error code: 50013): Missing Permissions`.

**Cause.**

* **Missing Access (50001)**: the bot cannot see the channel or the server. It happens when the bot lacks the **View Channel** permission, when it tries to use a channel from another server, or when it registers slash commands in a server it joined without the `applications.commands` scope.
* **Missing Permissions (50013)**: the bot can see the channel but lacks the permission for the action. Examples: sending a message, deleting a message, assigning a role. To assign or remove a role, the bot's role must sit **above** that role in the server's role list.

**Fix.**

1. In the portal, under **OAuth2 → URL Generator**, select the `bot` and `applications.commands` scopes and the permissions the bot uses.
2. Open the generated link and invite the bot again. It does not leave the server; it just gets the new permissions.
3. Check the channel permissions: a channel override can deny what the role allows.
4. To manage roles, drag the bot's role above the roles it assigns.

## Cannot find module (dependency missing from package.json)

```text theme={"system"}
Error: Cannot find module 'discord.js'
Require stack:
- /app/index.js
```

With `import` (ESM), the message is `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'discord.js'`. In Python, the equivalent is `ModuleNotFoundError: No module named 'discord'`.

**Cause.** On your PC the library exists in the `node_modules` folder, but it is not in `package.json`. On a host, dependencies are installed from scratch based on the manifest, so anything not declared does not exist.

Other causes that produce the same message:

* **`package.json` is inside a folder in the ZIP.** The install step cannot find the manifest. Put the files at the root of the ZIP.
* **Upper and lower case in paths.** `require("./Commands/ping")` works on Windows and macOS with a `commands` folder, but fails on Linux. Use the exact folder and file name.
* **In Python, the library is not in `requirements.txt`.** Watch the name: the package is `discord.py`, but the import is `import discord`.

**Fix.**

```bash theme={"system"}
npm install discord.js   # installs and saves to "dependencies" in package.json
```

In Python, add the library to `requirements.txt`, one per line (for example, `discord.py>=2.4`).

Upload the updated `package.json` and `package-lock.json` (or `requirements.txt`) and deploy again. Do not upload the `node_modules` folder: Hyze installs dependencies from the manifest.

## Bot is online but does not respond to messages

No error shows up. The bot is online in the server, but commands like `!ping` do nothing. In discord.py, the log usually shows this warning:

```text theme={"system"}
Privileged message content intent is missing, commands may not work as expected.
```

**Cause.** The **Message Content** intent is missing. Without it, Discord delivers messages with empty text, and the bot has nothing to match against the command prefix. The intent must be on in two places: in your code and in the Developer Portal.

**Fix.**

1. In the portal, under **Bot → Privileged Gateway Intents**, turn on **Message Content Intent**.
2. Request the intent in your code:

```js discord.js theme={"system"}
const { Client, GatewayIntentBits } = require("discord.js");

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});
```

```python discord.py theme={"system"}
import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix="!", intents=intents)
```

3. Deploy again.

> [!TIP]
>
> Slash commands (`/ping`) do not need the Message Content Intent. If the bot only uses slash commands, you can leave that intent off.

If you turned the intent on in code but forgot the portal, the error becomes `Used disallowed intents` (discord.js) or `PrivilegedIntentsRequired` (discord.py). Both sections are at the top of this page.

## Next steps

> **[Bot online 24/7](https://docs.hyzecloud.app/en/guides/discord-bot-24h.md)**
>
> The full walkthrough for hosting your bot.

> **[View app logs](https://docs.hyzecloud.app/en/guides/view-logs.md)**
>
> Fetch logs through the API too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.