Pycord

Common errors

• discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting privileged intents that have not been explicitly enabled in the developer portal.

  cause Your bot is attempting to use a privileged intent (e.g., Message Content, Members, or Presences) that has not been enabled in your Discord Developer Portal settings or not specified in your bot's code.
  fix Go to the Discord Developer Portal, select your application, navigate to the 'Bot' tab, and enable the necessary privileged intents under 'Privileged Gateway Intents'. Also, ensure these intents are passed to your `discord.Bot` or `discord.Client` instance (e.g., `intents.message_content = True`).

• discord.errors.Forbidden: 403 Forbidden (error code: 50001): Missing Access

  cause Your bot lacks the necessary permissions to perform an action (e.g., sending messages in a channel, assigning roles, kicking members) in the Discord server. This can be due to bot role hierarchy or missing permissions in the developer portal/server.
  fix Check your bot's role permissions in the Discord server and ensure its highest role is above the roles it's trying to manage. Also, verify that the bot has the required permissions enabled in the Discord Developer Portal and during its invite process (OAuth2 URL Generator). If MFA is required for the server, ensure your developer account has it enabled.

• message.content is empty / Bot not reading message content

  cause The `message_content` privileged intent is not enabled, preventing your bot from accessing the content of messages sent by other users.
  fix Enable the 'Message Content Intent' in your bot's settings on the Discord Developer Portal, and ensure `intents.message_content = True` is set when initializing your `discord.Bot` or `discord.Client` instance.

• discord.errors.HTTPException: 400 Bad Request (error code: 50035): Invalid Form Body

  cause This error often occurs with slash commands when required options are defined after optional ones, or when the message content (e.g., in an embed) is malformed or empty, or exceeds Discord's character limits (2000 characters for a message).
  fix For slash commands, ensure all required options are placed before any optional options. For messages, verify the content is not empty, does not exceed 2000 characters, and any embeds or components are correctly structured and populated.

Warnings

• breaking Pycord v2.7.0 dropped support for Python 3.8 and 3.9. Python 3.7 and below were dropped in v2.0. The library currently requires Python >=3.10 and <3.14.
  Fix: Upgrade your Python environment to version 3.10 or higher (up to 3.13) to ensure compatibility.
• breaking Gateway Intents are now explicitly required when initializing `discord.Client` or `discord.Bot`. Additionally, `Intents.message_content`, `Intents.members`, and `Intents.presences` are 'privileged intents' and must be manually enabled in your bot's Discord Developer Portal settings.
  Fix: Initialize your bot with `intents = discord.Intents.default()` (or specific intents) and pass them to the bot constructor (`bot = discord.Bot(intents=intents)`). For privileged intents, also enable them in the Discord Developer Portal under your bot's settings.
• breaking Migrating from py-cord v1.x to v2.x involves significant breaking changes, including a new `discord.Bot` class for application commands, redesigned UI components, removal of user account support, and changes to webhook handling. Old `discord.py` code may require substantial updates.
  Fix: Refer to the official 'Migrating to v2.0' guide in the Pycord documentation for a comprehensive list of changes and migration steps.
• gotcha A `KeyError` could occur when fetching application information or checking ownership (`is_owner`) due to `read_only` team members not being considered owners. This was a recent fix.
  Fix: Upgrade Pycord to version 2.7.2 or later to include the fix.

Install

• pip install -U py-cord Basic installation
• pip install -U "py-cord[voice]" With voice support

Imports

• Bot

  from discord import Bot

  The primary class for creating a Discord bot with command handling capabilities.
• Client

  from discord import Client

  A lower-level alternative to Bot, often used for simple event-driven bots without command framework needs.
• Intents

  from discord import Intents

  Required for specifying which events your bot will receive from Discord.
• ApplicationContext

  from discord import ApplicationContext

  The context object passed to application commands (e.g., slash commands).

Quickstart

This quickstart demonstrates a basic Pycord bot that comes online and responds to a slash command '/hello'. It highlights the use of `discord.Bot`, `Intents`, and retrieving the bot token from an environment variable for security. Remember to enable the 'Message Content' privileged intent in your bot's Discord Developer Portal settings for `intents.message_content = True` to function correctly.

import discord
import os

# Enable necessary intents. message_content is privileged for text commands.
intents = discord.Intents.default()
intents.message_content = True # Required for reading message content in commands or on_message events

bot = discord.Bot(intents=intents)

@bot.event
async def on_ready():
    print(f"{bot.user} is ready and online!")

@bot.slash_command(name="hello", description="Say hello to the bot")
async def hello(ctx: discord.ApplicationContext, name: str = None):
    """Says hello to the user or a specified name."""
    name = name or ctx.author.name
    await ctx.respond(f"Hello {name}!")

# Run the bot with the token from environment variables
# Make sure to set a 'TOKEN' environment variable with your bot's token
bot.run(os.environ.get('TOKEN'))