별책부록 14편
트러블슈팅 50개
봇 운영 중 자주 만나는 에러 — 에러 메시지로 찾아서 바로 해결하세요
📑 이 챕터에서 다룰 내용
봇 운영 중 에러는 무조건 발생합니다. 미리 알아두면 당황하지 않고 빠르게 해결할 수 있어요. 이 편은 reference 형식입니다 — 에러 메시지로 검색해서 해당 항목을 찾으세요. 총 50개, 카테고리 A~E로 분류되어 있습니다.
💡 빠르게 찾는 법
브라우저에서 Ctrl+F (Windows) / Cmd+F (Mac)를 눌러 에러 메시지의 핵심 단어를 검색하세요.
예: Permission denied, EACCES, rate_limit 등
1. Permission denied (publickey)
⚠️ 원인
SSH 키가 등록되지 않았거나 잘못 등록된 상태입니다.
🎉 해결
- 로컬 공개키 확인:
cat ~/.ssh/id_ed25519.pub - Contabo 대시보드에서 SSH 키 등록 여부 확인
- 서버에서
~/.ssh/authorized_keys확인
💻 명령어
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@서버IP
2. Connection refused
⚠️ 원인
- 서버가 켜지지 않은 상태
- 방화벽이 차단 중
- SSH 포트가 22번이 아닌 경우
🎉 해결
- Contabo 대시보드에서 서버 상태 확인
- 다른 포트 시도:
ssh -p 2222 user@서버IP - 방화벽 확인:
ufw status
3. Connection timed out
⚠️ 원인
네트워크 문제 또는 IP 주소가 잘못된 경우입니다.
🎉 해결
ping 서버IP— 응답 여부 확인- 다른 네트워크에서 시도 (모바일 데이터 전환)
- Contabo 대시보드에서 IP 주소 재확인
4. Host key verification failed
⚠️ 원인
서버 IP가 재사용된 경우입니다. 이전에 다른 서버가 쓰던 IP를 같은 IP로 받으면 발생해요.
💻 해결 명령어
ssh-keygen -R 서버IP # 그 다음 다시 ssh 시도
5. disk quota exceeded
⚠️ 원인
디스크 사용량이 100%에 도달한 상태입니다.
💻 해결 명령어
df -h # 사용량 확인 du -sh /var/log/* # 큰 로그 파일 찾기 sudo journalctl --vacuum-size=500M # journal 정리
6. out of memory
⚠️ 원인
RAM이 부족한 상태입니다. Cloud VPS 10에서 봇 4~5개 운영 시 자원 사용량을 반드시 점검하세요.
💻 해결 명령어
free -h # 메모리 사용량 확인 ps aux --sort=-%mem | head # 메모리 많이 쓰는 프로세스 sudo systemctl restart 봇이름 # 봇 재시작
7. apt-get update — could not connect
⚠️ 원인
네트워크 문제 또는 DNS 설정이 잘못된 경우입니다.
💻 해결 명령어
ping 8.8.8.8 # IP 연결 확인 ping google.com # DNS 작동 확인 # DNS 수정 echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
8. unable to fetch some archives
⚠️ 원인
apt 저장소가 일시적으로 응답하지 않는 경우입니다.
💻 해결 명령어
sudo apt-get update --fix-missing sudo apt-get install -f
9. cannot create directory: read-only file system
⚠️ 원인
디스크가 읽기 전용 모드로 마운트된 상태입니다. 심각한 상황이에요.
💻 해결 명령어
mount | grep " ro," # 읽기 전용 마운트 확인 sudo mount -o remount,rw / # 읽기·쓰기 모드로 재마운트 sudo reboot # 재시작 권장
10. Too many authentication failures
⚠️ 원인
SSH 키를 너무 많이 시도했거나, 여러 개의 키가 자동으로 시도되는 경우입니다.
💻 해결 명령어
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 user@서버IP
11. Cannot find module 'discord.js'
⚠️ 원인
패키지가 설치되지 않은 상태입니다.
💻 해결 명령어
cd /home/ubuntu/봇폴더 npm install # 또는 특정 패키지만 npm install discord.js
12. Error: Cannot find module './src/index'
⚠️ 원인
파일 경로가 잘못된 경우입니다.
💻 해결 명령어
ls src/ # 파일 목록 확인 node src/index.js # 정확한 경로로 실행
13. EACCES: permission denied
⚠️ 원인
파일 권한이 없는 경우입니다.
💻 해결 명령어
chmod 755 봇파일.sh chown -R ubuntu:ubuntu /home/ubuntu/봇폴더
14. npm ERR! code EACCES
⚠️ 원인
npm install 실행 권한이 없는 경우입니다.💡 올바른 해결 방법
주의: sudo npm install은 보안상 위험합니다. 사용하지 마세요.
nvm을 사용하거나 사용자 디렉터리를 지정하는 방법을 권장합니다.
💻 해결 명령어
mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc
15. ModuleNotFoundError: No module named 'anthropic'
⚠️ 원인
Python 패키지가 설치되지 않은 상태입니다.
💻 해결 명령어
pip install anthropic # 또는 venv 사용 (권장) python3 -m venv venv source venv/bin/activate pip install -r requirements.txt
16. Error: listen EADDRINUSE :::3000
⚠️ 원인
포트 3000번이 이미 다른 프로세스에서 사용 중입니다.
💻 해결 명령어
lsof -i :3000 # 사용 중인 프로세스 확인 kill -9 PID # 해당 프로세스 종료 # 또는 다른 포트 사용 PORT=3001 npm start
17. UnhandledPromiseRejectionWarning
⚠️ 원인
Promise reject가 처리되지 않은 경우입니다.
💻 해결 — try/catch 추가
async function main() {
try {
await yourCode();
} catch (err) {
console.error('Error:', err);
Sentry.captureException(err);
}
}18. RangeError: Maximum call stack size exceeded
⚠️ 원인
무한 재귀 호출이 발생한 경우입니다.
💡 해결 방법
- 재귀 함수의 종료 조건을 반드시 확인하세요
- for/while 루프로 변경하는 것을 권장합니다
19. SyntaxError: Unexpected token
⚠️ 원인
코드 문법 오류입니다.
💡 해결 방법
- 따옴표·괄호 짝을 확인하세요
- 끝에 세미콜론·괄호가 빠진 곳을 찾아보세요
- ESLint 사용을 권장합니다
20. MODULE_NOT_FOUND: discord.js (버전 불일치)
⚠️ 원인
discord.js v12와 v13/v14 사이의 코드 방식이 다릅니다.
💻 해결 — package.json 버전 확인 및 코드 수정
# package.json 버전 확인
"discord.js": "^14.0.0" // 현재 버전
# v14+ 방식으로 코드 변경
import { Client, GatewayIntentBits } from 'discord.js';21. DiscordAPIError[10003]: Unknown Channel
⚠️ 원인
채널 ID가 잘못된 경우입니다.
💡 해결 방법
- 봇이 해당 채널에 접근 권한이 있는지 확인하세요
- Discord 개발자 모드를 활성화 → 채널 ID를 다시 복사하세요
22. DiscordAPIError[50001]: Missing Access
⚠️ 원인
봇이 서버·채널에 접근 권한이 없는 상태입니다.
💡 해결 방법
- 봇 초대 URL에서 필요한 권한을 다시 확인하세요
- 서버 설정 → 봇 역할에 필요한 권한을 추가하세요
23. DiscordAPIError[50013]: Missing Permissions
⚠️ 원인
메시지 보내기·읽기 권한이 없는 상태입니다.
💡 해결 방법
- 채널 설정 → 봇 역할에 "메시지 보내기" 권한을 추가하세요
- 서버 관리자에게 권한 추가를 요청하세요
24. Privileged Intents required
⚠️ 원인
MESSAGE_CONTENT_INTENT 또는 SERVER_MEMBERS_INTENT가 활성화되지 않은 상태입니다.🎉 해결 순서
- discord.com/developers/applications 접속
- 본인 봇 → Bot 메뉴 클릭
- "MESSAGE CONTENT INTENT" 토글 ON
- 봇 재시작
25. WebSocket: Heartbeat acknowledgement
⚠️ 원인
네트워크가 일시적으로 끊긴 경우입니다.
💡 해결 방법
- 자동 재연결은 대부분의 라이브러리에 기본으로 포함되어 있어요
- 자주 발생한다면 systemd 자동 재시작 설정을 확인하세요
26. Telegram: 401 Unauthorized
⚠️ 원인
봇 토큰이 잘못된 경우입니다.
🎉 해결 순서
- BotFather에서 토큰을 다시 확인하세요
.env파일의 토큰을 수정하세요- 봇을 재시작하세요
27. Telegram: 429 Too Many Requests
⚠️ 원인
Telegram API 발송 한도를 초과한 경우입니다.
💡 해결 방법
- 메시지 발송 간격을 늘리세요 (1초에 1개 권장)
- batch 발송 방식으로 변경하세요
28. Telegram: Forbidden: bot was blocked by the user
📘 참고
사용자가 봇을 차단한 정상적인 상황입니다. 에러로 처리하지 말고, 아래처럼 조용히 건너뛰세요.
💻 코드 예시 — 차단 처리
if (err.message.includes('blocked by the user')) {
await markUserAsBlocked(userId);
return; // 에러 없이 종료
}29. Discord 봇 응답 5초 이상 지연
⚠️ 원인
Anthropic API 응답 시간 때문입니다. 5~30초는 정상 범위예요.
💻 해결 — 중간 메시지 먼저 보내기
await msg.reply("생각 중... 🤔");
const reply = await callClaude(question);
await msg.edit(reply);30. Discord 메시지 2000자 초과
⚠️ 원인
Discord 메시지 한도는 2000자입니다. 긴 응답은 잘려서 오류가 발생해요.
💻 해결 — 메시지 분할 발송
if (text.length > 2000) {
const chunks = text.match(/.{1,1900}/g);
for (const chunk of chunks) {
await channel.send(chunk);
}
}31. Error: 401 Unauthorized
⚠️ 원인
API 키가 없거나 잘못된 경우입니다.
🎉 해결 순서
- console.anthropic.com에서 키를 확인하세요
.env파일의 키를 수정하세요- 환경 변수 재로드:
source .env
32. Error: 429 rate_limit_error
⚠️ 원인
분당 RPM·일별 RPD 한도를 초과한 경우입니다.
💡 해결 방법
- exponential backoff를 구현하세요 (별책부록 6편 참고)
- 사용량을 줄이거나
- Tier 1 → Tier 2로 자동 상향됩니다 (사용량이 충분히 쌓이면)
33. Error: 500 server_error
⚠️ 원인
Anthropic 서버가 일시적으로 오류 상태입니다.
💡 해결 방법
- 자동 retry를 3회 시도하세요
- status.anthropic.com에서 서버 상태를 확인하세요
34. Error: 529 overloaded_error
⚠️ 원인
Anthropic 서버가 일시적으로 과부하 상태입니다.
💡 해결 방법
- 30초 대기 후 retry하세요
- exponential backoff 전략을 사용하세요
35. Error: invalid_request_error: max_tokens too large
⚠️ 원인
max_tokens 값이 모델 한도를 초과한 경우입니다.
📘 모델별 max_tokens 한도
- Sonnet 4.6 max: 64,000 토큰
- Opus 4.7 max: 128,000 토큰
응답 길이에 맞게 max_tokens=4096 정도로 적절히 설정하세요.
36. Error: invalid_request_error: messages: at least one message
⚠️ 원인
messages 배열이 비어있는 경우입니다.
💻 해결 — messages 배열 확인
messages = [
{"role": "user", "content": "질문"}
]
# 빈 배열은 허용되지 않습니다37. Anthropic 응답이 잘림 (truncate)
⚠️ 원인
max_tokens 값이 너무 작게 설정된 경우입니다.
💡 해결 방법
- max_tokens 값을 늘리세요
- 또는 streaming 방식을 사용하세요 (stream=True 시 잘리지 않습니다)
38. prompt_too_long
⚠️ 원인
system + messages 합산이 컨텍스트 윈도우를 초과한 경우입니다.
📘 참고
Sonnet 4.6 / Opus 4.7는 모두 1M 컨텍스트를 지원합니다. 단, 비용이 크게 늘어나므로 prompt caching 사용을 권장합니다.
39. Anthropic 비용 갑자기 증가
⚠️ 원인
- 사용량 자체가 증가한 경우
- Opus 4.7의 새 토크나이저 (35% 더 많은 토큰 소비)
- prompt caching이 제대로 작동하지 않는 경우
🎉 해결 방법
- console.anthropic.com에서 비용을 분석하세요
prompt_cache_hit_rate를 확인하세요 (90% 이상 권장)- system prompt에 caching이 적용되어 있는지 확인하세요
40. Streaming 도중 끊김
⚠️ 원인
네트워크가 일시적으로 끊긴 경우입니다.
💻 해결 — try/except로 안전하게 처리
try:
async for chunk in stream:
# 청크 처리
pass
except Exception:
# 마지막까지 처리된 내용을 그대로 사용
pass41. systemctl: command not found
⚠️ 원인
systemd가 없는 구버전 Linux입니다.
💡 해결 방법
- Ubuntu 22.04 이상을 사용하세요 (systemd 기본 포함)
- 또는 pm2를 대안으로 사용하세요
42. Failed to start 봇.service
⚠️ 원인
.service 파일이 없거나 내용이 잘못된 경우입니다.
💻 해결 명령어 — 로그 확인
sudo systemctl status 봇.service # 에러 내용 확인 journalctl -u 봇.service -n 50 # 최근 50줄 로그
43. systemd 봇 재시작 무한 loop
⚠️ 원인
봇이 시작 직후 종료 → systemd가 재시작 → 또 종료하는 패턴이 반복됩니다.
🎉 해결 방법
먼저 봇 로그를 확인해서 왜 종료되는지 파악하세요. 그 후 아래 설정을 추가하세요.
💻 .service 파일에 추가
[Service] StartLimitBurst=5 StartLimitInterval=300s
44. pm2: command not found
⚠️ 원인
pm2가 설치되지 않은 상태입니다.
💻 해결 명령어
npm install -g pm2 # nvm 사용 중이라면 nvm 환경에서 실행하세요
45. pm2 재시작 후 봇이 시작되지 않음
⚠️ 원인
pm2 save를 하지 않은 경우입니다.💻 해결 명령어
pm2 start 봇 pm2 save # 필수! pm2 startup # 부팅 시 자동 시작 등록
46. pm2 logs에서 한글 깨짐
⚠️ 원인
LANG·LC_ALL 환경 변수가 설정되지 않은 경우입니다.
💻 해결 — ecosystem.config.js에 추가
env: {
LANG: 'ko_KR.UTF-8',
LC_ALL: 'ko_KR.UTF-8',
}47. systemd 환경 변수가 적용되지 않음
⚠️ 원인
EnvironmentFile= 설정이 잘못된 경우입니다.💻 .service 파일 올바른 설정
[Service] EnvironmentFile=/home/ubuntu/봇/.env # .env 파일 내용 예시: ANTHROPIC_API_KEY=sk-ant-... DISCORD_TOKEN=...
48. pm2 monit에서 CPU 100%
⚠️ 원인
봇 코드에서 무한 루프가 발생 중입니다.
💡 해결 방법
pm2 stop 봇으로 즉시 중단하세요- 코드에서 무한 루프 구간을 찾아 수정하세요
pm2 restart 봇으로 재시작하세요
49. systemd timer 설정 방법
💡 systemd timer를 권장하는 이유
cron보다 systemd timer가 더 안정적입니다. 부팅 후 자동 실행되고, 정확한 시간 설정이 가능해요.
💻 /etc/systemd/system/봇.timer 설정 예시
[Unit] Description=봇 매일 09:00 [Timer] OnCalendar=*-*-* 09:00:00 Asia/Seoul [Install] WantedBy=timers.target # 활성화 sudo systemctl enable 봇.timer sudo systemctl start 봇.timer
50. 봇 메모리 leak
⚠️ 원인
Node.js·Python에서 메모리가 조금씩 누수되는 경우입니다. 드물지만 발생해요.
💻 해결 — 메모리 상한 설정
# pm2 방식
{ name: "봇", max_memory_restart: "500M" }
# systemd 방식
[Service]
MemoryMax=500M
MemoryHigh=400M📌 14편 정리
- 50개 에러를 A(SSH)·B(Node/Python)·C(봇 API)·D(Anthropic)·E(systemd/pm2) 5개 카테고리로 분류했습니다
- 핵심 원칙 1: 에러 메시지를 정확히 읽으면 70%는 그 자리에서 해결됩니다
- 핵심 원칙 2: 로그를 항상 먼저 확인하세요 (
journalctl또는pm2 logs) - 핵심 원칙 3: 해결이 안 되면 Anthropic·Discord·Telegram 공식 문서를 참고하세요
- 새 에러를 만나면 위 패턴에서 가장 가까운 항목을 찾아 적용해 보세요