> ## 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.

# Erros comuns ao hospedar um bot de Discord

> Erros comuns ao hospedar um bot de Discord e como corrigir: Used disallowed intents, TokenInvalid, Missing Permissions, Cannot find module e mais.

Cada seção abaixo começa pela mensagem exata que aparece no log. Na Hyze Cloud, os logs ficam no app, em **Observabilidade → Console**. Se o deploy falhou antes de o bot ligar, veja a aba **Deploys**.

## Used disallowed intents (discord.js)

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

Em versões antigas do discord.js, a mesma falha aparece como `Privileged intent provided is not enabled or whitelisted`.

**Causa.** O código pede um intent privilegiado, mas ele está desligado no Developer Portal. Os intents privilegiados são três: `GuildMembers`, `GuildPresences` e `MessageContent`.

**Correção.**

1. Abra o [Discord Developer Portal](https://discord.com/developers/applications), escolha o bot e vá em **Bot**.
2. Em **Privileged Gateway Intents**, ligue os intents que o código pede: **Server Members Intent**, **Presence Intent** ou **Message Content Intent**.
3. Salve e reinicie o bot.

Se o bot não usa um desses intents, tire ele da lista de `intents` no `new Client(...)`.

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

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

**Causa.** O `client.login()` recebeu um token errado ou vazio. Em hospedagem, o motivo mais comum é a variável de ambiente não existir: `process.env.DISCORD_TOKEN` chega como `undefined`.

**Correção.**

* Confira se a variável `DISCORD_TOKEN` está cadastrada no app, com esse nome exato. Na Hyze: **Configurações → Variáveis de ambiente**.
* Confira se o código lê o mesmo nome: `client.login(process.env.DISCORD_TOKEN)`.
* Cole o token sem aspas e sem espaços no começo ou no fim.
* Se você gerou um token novo no portal, o antigo deixou de valer. Atualize a variável.
* Depois de mudar a variável, reinicie o app. Variáveis de ambiente são lidas quando o processo inicia.

## 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.
```

**Causa.** É o mesmo problema do `Used disallowed intents`: o código liga `intents.members`, `intents.presences` ou `intents.message_content`, mas o intent está desligado no Developer Portal.

**Correção.** No portal, em **Bot → Privileged Gateway Intents**, ligue os intents que o código usa e reinicie o bot. Se o bot não precisa de um deles, deixe ele como `False` no código.

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

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

**Causa.** O token passado para `client.run()` está errado, foi trocado no portal ou veio com espaço ou aspas a mais. Se a variável nem existir, o erro muda: `os.environ["DISCORD_TOKEN"]` levanta `KeyError` e `os.getenv("DISCORD_TOKEN")` devolve `None`, que o discord.py recusa.

**Correção.**

* Copie o token de novo em **Bot → Reset Token** no Developer Portal.
* Cadastre como `DISCORD_TOKEN` nas variáveis de ambiente do app, sem aspas.
* Leia com `os.environ["DISCORD_TOKEN"]`. Se faltar, o log mostra o nome da variável na hora.
* Reinicie o app depois de mudar a variável.

## Missing Access e Missing Permissions

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

No discord.py, os mesmos erros aparecem como `discord.errors.Forbidden: 403 Forbidden (error code: 50001): Missing Access` e `(error code: 50013): Missing Permissions`.

**Causa.**

* **Missing Access (50001)**: o bot não enxerga o canal ou o servidor. Acontece quando ele não tem a permissão **Ver canal**, quando tenta usar um canal de outro servidor ou quando registra comandos de barra num servidor em que foi convidado sem o escopo `applications.commands`.
* **Missing Permissions (50013)**: o bot vê o canal, mas não tem a permissão da ação. Exemplos: enviar mensagem, apagar mensagem, dar cargo. Para dar ou tirar um cargo, o cargo do bot precisa estar **acima** dele na lista de cargos do servidor.

**Correção.**

1. No portal, em **OAuth2 → URL Generator**, marque os escopos `bot` e `applications.commands` e as permissões que o bot usa.
2. Abra o link gerado e convide o bot de novo. Ele não sai do servidor, só recebe as permissões novas.
3. Confira as permissões do canal: uma regra do canal pode negar o que o cargo libera.
4. Para gerenciar cargos, arraste o cargo do bot para cima dos cargos que ele vai dar.

## Cannot find module (dependência fora do package.json)

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

Com `import` (ESM), a mensagem é `Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'discord.js'`. No Python, o equivalente é `ModuleNotFoundError: No module named 'discord'`.

**Causa.** No seu PC a biblioteca existe na pasta `node_modules`, mas não está no `package.json`. Na hospedagem, as dependências são instaladas do zero a partir do manifesto, então o que não está declarado não existe.

Outras causas que dão a mesma mensagem:

* **O `package.json` está dentro de uma pasta no ZIP.** A instalação não acha o manifesto. Coloque os arquivos na raiz do ZIP.
* **Maiúscula e minúscula no caminho.** `require("./Commands/ping")` funciona no Windows e no macOS com a pasta `commands`, mas falha no Linux. Use o nome exato da pasta e do arquivo.
* **No Python, a biblioteca não está no `requirements.txt`.** Atenção ao nome: o pacote é `discord.py`, mas o import é `import discord`.

**Correção.**

```bash theme={"system"}
npm install discord.js   # instala e grava em "dependencies" no package.json
```

No Python, adicione a biblioteca ao `requirements.txt`, uma por linha (por exemplo, `discord.py>=2.4`).

Envie o `package.json` e o `package-lock.json` atualizados (ou o `requirements.txt`) e faça um novo deploy. Não envie a pasta `node_modules`: a Hyze instala as dependências a partir do manifesto.

## Bot fica online mas não responde a mensagens

Não aparece erro nenhum. O bot está online no servidor, mas comandos como `!ping` não fazem nada. No discord.py, o log costuma mostrar este aviso:

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

**Causa.** Falta o intent **Message Content**. Sem ele, o Discord entrega as mensagens com o texto vazio, e o bot não tem o que comparar com o prefixo do comando. O intent precisa estar ligado em dois lugares: no código e no Developer Portal.

**Correção.**

1. No portal, em **Bot → Privileged Gateway Intents**, ligue **Message Content Intent**.
2. Peça o intent no código:

```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. Faça um novo deploy.

> [!TIP]
>
> Comandos de barra (`/ping`) não precisam do Message Content Intent. Se o bot só usa comandos de barra, você pode deixar esse intent desligado.

Se você ligou o intent no código e esqueceu o portal, o erro muda para `Used disallowed intents` (discord.js) ou `PrivilegedIntentsRequired` (discord.py). As duas seções estão no começo desta página.

## Próximos passos

> **[Bot online 24 horas](https://docs.hyzecloud.app/pt/guides/discord-bot-24h.md)**
>
> O passo a passo completo para hospedar o bot.

> **[Ver logs do app](https://docs.hyzecloud.app/pt/guides/view-logs.md)**
>
> Busque os logs também pela API.


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