디스코드 봇 오류 해결 총정리 - intents·token 에러부터 봇이 반응 없을 때까지!

안녕하세요! Mojangcam입니다 😎

디스코드 봇 만들기 시리즈를 9편까지 진행하면서 가장 많이 받는 질문이 뭔지 아세요? 바로 "봇이 안 켜져요", "에러가 떠요"예요! 사실 봇 개발에서 코드를 짜는 시간보다 에러랑 싸우는 시간이 더 길 때도 많죠 😅

그래서 오늘은 디스코드 봇 입문자가 가장 자주 만나는 에러 5가지를 증상 → 원인 → 해결 순서로 싹 정리했어요. 이 글 하나만 즐겨찾기 해두면 에러 사전처럼 쓸 수 있을 거예요!

📌 시작 전에 - 환경 확인부터!

에러 해결의 절반은 버전 확인이에요. 이 글은 아래 환경 기준으로 작성했어요.

• Python 3.8 이상 (3.10+ 권장)
• discord.py 2.x (2026-07 기준 최신 2.7.1)

pip install -U discord.py
pip show discord.py

pip show discord.py로 지금 설치된 버전을 꼭 확인해주세요. 1.x 시절 코드(구버전 강좌)를 2.x에서 돌리면 여기 없는 이상한 에러가 나올 수 있어요!

📌 1. PrivilegedIntentsRequired - 특권 인텐트 에러

증상

봇을 실행하자마자 이런 에러가 뜨면서 꺼져요.

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

원인

코드에서는 인텐트(Intents)를 켰는데, 디스코드 개발자 포털에서 스위치를 안 켰기 때문이에요. 멤버 목록(members), 상태(presences), 메시지 내용(message_content) 이 3가지는 '특권 인텐트'라서 코드와 포털 양쪽 모두 켜야 작동해요.

해결

1. 디스코드 개발자 포털 → 내 애플리케이션 → Bot 탭으로 가주세요.
2. Privileged Gateway Intents 섹션에서 필요한 스위치(PRESENCE / SERVER MEMBERS / MESSAGE CONTENT INTENT)를 켜고 저장!

이제 코드에서는 필요한 것만 켜면 돼요.

# discord.py 2.7.x / Python 3.8+
import discord
from discord.ext import commands

intents = discord.Intents.default()
intents.message_content = True  # 메시지 내용을 읽어야 할 때만!

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

하나씩 뜯어볼게요 💡

• Intents.default() : 특권 인텐트를 제외한 기본 인텐트 묶음이에요.
• intents.message_content = True : 특권 인텐트 중 메시지 내용만 추가로 켜는 거예요.
• Intents.all()을 쓰면 포털에서 스위치 3개를 전부 켜야 해요. 하나라도 꺼져 있으면 이 에러가 납니다!

💬 참고로 봇이 100개 이상 서버에 들어가면(인증 봇) 특권 인텐트는 디스코드 승인을 따로 받아야 해요. 입문 단계에서는 신경 안 써도 됩니다!

📌 2. LoginFailure: Improper token has been passed

증상

discord.errors.LoginFailure: Improper token has been passed.

원인

토큰이 잘못됐다는 뜻인데, 실제 원인은 거의 이 셋 중 하나예요.

1. 토큰 복사가 잘못됨 (앞뒤 공백, 일부 누락)
2. 포털에서 Reset Token을 눌러서 예전 토큰이 무효화됨
3. 봇 토큰이 아니라 Client Secret이나 애플리케이션 ID를 붙여넣음 (진짜 많이 하는 실수!)

해결

개발자 포털 → Bot 탭 → Reset Token으로 새 토큰을 발급받아 통째로 다시 복사하세요. 토큰은 Bot 탭에 있는 거예요. OAuth2 탭의 Client Secret이 아니에요!

그리고 토큰은 코드에 직접 쓰지 말고 .env 파일로 관리하는 습관을 들이면 좋아요.

pip install python-dotenv

# discord.py 2.7.x / Python 3.8+
import os
from dotenv import load_dotenv

load_dotenv()
TOKEN = os.getenv("DISCORD_TOKEN")

bot.run(TOKEN)

.env 파일은 이렇게 만들어주세요 (같은 폴더에!)

DISCORD_TOKEN=여기에_토큰_붙여넣기

💡 주의: 토큰이 들어간 코드를 깃허브에 올리면 디스코드가 자동으로 감지해서 토큰을 무효화해버려요. 갑자기 이 에러가 났다면 '내가 코드를 어디 올렸나?'부터 떠올려보세요!

📌 3. 봇은 켜졌는데 명령어에 반응이 없어요 (에러 없음)

증상

on_ready까지 잘 뜨고 봇도 온라인인데, !hello를 쳐도 아무 반응이 없어요. 에러도 안 떠서 제일 답답한 케이스죠 😭

원인

십중팔구 message_content 인텐트가 꺼져 있어서예요. 봇이 메시지 '내용'을 못 읽으니 명령어인지도 모르는 거죠. 코드와 포털 중 한쪽만 켜져 있어도 이렇게 돼요. (이때는 에러 대신 터미널에 경고 한 줄만 슬쩍 나와서 놓치기 쉬워요!)

해결

1. 코드: intents.message_content = True 확인 (1번 에러의 코드 참고)
2. 포털: MESSAGE CONTENT INTENT 스위치 ON 확인
3. 접두사 확인: command_prefix="!"인데 ?hello를 치고 있진 않은지!
4. 슬래시 명령어(/명령어)가 안 보이는 거라면 → tree.sync()를 했는지 확인하세요. 동기화 직후엔 디스코드 클라이언트를 재시작(Ctrl+R)해야 보일 때도 있어요.

@bot.event
async def on_ready():
    await bot.tree.sync()  # 슬래시 명령어 동기화
    print(f"{bot.user} 로그인 완료!")

📌 4. ModuleNotFoundError: No module named 'discord'

증상

ModuleNotFoundError: No module named 'discord'

원인

1. discord.py를 설치 안 함
2. 파이썬이 여러 개 설치돼 있어서 다른 파이썬에 설치됨 (제일 흔해요!)
3. 내 코드 파일 이름이 discord.py라서 진짜 라이브러리 대신 내 파일을 import함

해결

설치는 패키지 이름 discord.py로, import는 discord로 해요.

# 지금 실행하는 파이썬에 정확히 설치하기
python -m pip install -U discord.py

# 윈도우에서 py 런처를 쓴다면
py -3 -m pip install -U discord.py

그냥 pip install이 아니라 python -m pip으로 설치하면 '실행하는 파이썬'과 '설치되는 파이썬'이 어긋나는 문제를 막을 수 있어요.

그리고 내 파일명이 discord.py면 지금 바로 바꿔주세요! (bot.py, main.py 추천) 파일명이 라이브러리와 겹치면 아래 같은 요상한 에러가 나요.

AttributeError: partially initialized module 'discord' has no attribute 'Intents'
(most likely due to a circular import)

같은 폴더에 discord.pyc나 __pycache__ 폴더가 생겼다면 그것도 같이 지워주세요!

📌 5. RuntimeError: Event loop is closed (윈도우)

증상

봇을 Ctrl+C로 종료할 때 마지막에 이런 에러가 우르르 떠요.

RuntimeError: Event loop is closed

원인

윈도우의 asyncio 이벤트 루프가 닫히는 타이밍에 네트워크 연결 정리가 겹치면서 나는 에러예요. 봇 동작에는 영향이 없는, 종료 과정의 잡음에 가까워요.

해결

• bot.run(TOKEN)으로 실행하고 있다면 그냥 무시해도 돼요. discord.py가 정리를 알아서 해줍니다.
• asyncio.run(...)으로 직접 실행부를 짰다면 bot.run() 방식으로 돌아가는 게 제일 간단한 해결책이에요.

📌 에러 안 나는 최소 시작 코드 (복붙 OK)

위 에러들을 전부 피해 가는 깨끗한 시작 코드예요. 새 봇 만들 때 이걸로 시작하세요!

# discord.py 2.7.x / Python 3.8+
# 파일명은 bot.py 등으로! (discord.py 금지)
import os

import discord
from discord.ext import commands
from dotenv import load_dotenv  # pip install python-dotenv

load_dotenv()
TOKEN = os.getenv("DISCORD_TOKEN")  # .env 파일에 DISCORD_TOKEN=토큰

intents = discord.Intents.default()
intents.message_content = True  # 포털 MESSAGE CONTENT INTENT도 ON!

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


@bot.event
async def on_ready():
    await bot.tree.sync()
    print(f"{bot.user} 로그인 완료!")


@bot.command()
async def hello(ctx):
    await ctx.send("안녕하세요! 👋")


bot.run(TOKEN)

📌 예방 체크리스트 - 다시 안 만나려면!

• ✅ pip show discord.py로 2.x 버전인지 확인했다
• ✅ 포털의 특권 인텐트 스위치와 코드의 intents 설정이 일치한다
• ✅ 토큰은 Bot 탭에서 복사했고, .env로 관리한다
• ✅ 토큰이 든 코드를 깃허브 등에 올리지 않는다
• ✅ 파일명이 discord.py가 아니다
• ✅ 설치는 python -m pip install -U discord.py로 했다

📌 마무리

오늘은 디스코드 봇 입문자가 가장 자주 만나는 에러 5가지를 정리해봤어요!

1. PrivilegedIntentsRequired → 포털에서 인텐트 스위치 ON
2. Improper token → Bot 탭에서 토큰 재발급 + .env 관리
3. 반응 없음 → message_content 인텐트 + 접두사 + sync 확인
4. No module named 'discord' → python -m pip 설치 + 파일명 변경
5. Event loop is closed → bot.run() 사용 시 무시 OK

에러는 여러분이 뭔가 만들고 있다는 증거예요. 이 글이 에러와 싸우는 시간을 확 줄여줬으면 좋겠네요! 궁금한 에러가 있다면 댓글로 남겨주세요. 다음 글에서는 파이썬으로 엑셀 업무를 자동화하는 방법도 다뤄볼 예정이니 기대해주세요 🙌

📚 디스코드 봇 만들기 시리즈

• #1 - Slash Command 완전 정복!
• #2 - Slash Command에 옵션(Arguments) 추가하기!
• #3 - Slash Command에 서브 커맨드(Subcommand) 넣기!
• #4 - Slash Command로 임베드 전송하기!
• #5 - 버튼(Button) 상호작용 구현하기!
• #6 - 드롭다운(Select Menu) 메뉴 구현하기!
• #7 - 모달(Modal)로 입력 받기 구현하기 (파이썬 예제)
• #8 - 임베드(Embed) 이미지·필드로 꾸미기 (파이썬 예제)
• #9 - AI(Claude·ChatGPT API) 연동하기! (파이썬 예제)
• 번외 - 디스코드 봇 24시간 무료 호스팅 총정리 (2026)