별책부록 14편
별책부록 14편
트러블슈팅 50개
봇 운영 중 자주 만나는 에러 — 에러 메시지로 찾아서 바로 해결하세요
📑 이 챕터에서 다룰 내용

봇 운영 중 에러는 무조건 발생합니다. 미리 알아두면 당황하지 않고 빠르게 해결할 수 있어요. 이 편은 reference 형식입니다 — 에러 메시지로 검색해서 해당 항목을 찾으세요. 총 50개, 카테고리 A~E로 분류되어 있습니다.

💡 빠르게 찾는 법

브라우저에서 Ctrl+F (Windows) / Cmd+F (Mac)를 눌러 에러 메시지의 핵심 단어를 검색하세요.

예: Permission denied, EACCES, rate_limit

A SSH·서버 에러 (1~10번) 🔗

1. Permission denied (publickey)

⚠️ 원인
SSH 키가 등록되지 않았거나 잘못 등록된 상태입니다.
🎉 해결
  1. 로컬 공개키 확인: cat ~/.ssh/id_ed25519.pub
  2. Contabo 대시보드에서 SSH 키 등록 여부 확인
  3. 서버에서 ~/.ssh/authorized_keys 확인
💻 명령어
ssh-copy-id -i ~/.ssh/id_ed25519.pub root@서버IP

2. Connection refused

⚠️ 원인
  • 서버가 켜지지 않은 상태
  • 방화벽이 차단 중
  • SSH 포트가 22번이 아닌 경우
🎉 해결
  1. Contabo 대시보드에서 서버 상태 확인
  2. 다른 포트 시도: ssh -p 2222 user@서버IP
  3. 방화벽 확인: ufw status

3. Connection timed out

⚠️ 원인
네트워크 문제 또는 IP 주소가 잘못된 경우입니다.
🎉 해결
  1. ping 서버IP — 응답 여부 확인
  2. 다른 네트워크에서 시도 (모바일 데이터 전환)
  3. 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
B Node.js·Python 에러 (11~20번) 🔗

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';
C Discord·Telegram 봇 에러 (21~30번) 🔗

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가 활성화되지 않은 상태입니다.
🎉 해결 순서
  1. discord.com/developers/applications 접속
  2. 본인 봇 → Bot 메뉴 클릭
  3. "MESSAGE CONTENT INTENT" 토글 ON
  4. 봇 재시작

25. WebSocket: Heartbeat acknowledgement

⚠️ 원인
네트워크가 일시적으로 끊긴 경우입니다.
💡 해결 방법
  • 자동 재연결은 대부분의 라이브러리에 기본으로 포함되어 있어요
  • 자주 발생한다면 systemd 자동 재시작 설정을 확인하세요

26. Telegram: 401 Unauthorized

⚠️ 원인
봇 토큰이 잘못된 경우입니다.
🎉 해결 순서
  1. BotFather에서 토큰을 다시 확인하세요
  2. .env 파일의 토큰을 수정하세요
  3. 봇을 재시작하세요

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);
  }
}
D Anthropic API 에러 (31~40번) 🔗

31. Error: 401 Unauthorized

⚠️ 원인
API 키가 없거나 잘못된 경우입니다.
🎉 해결 순서
  1. console.anthropic.com에서 키를 확인하세요
  2. .env 파일의 키를 수정하세요
  3. 환경 변수 재로드: source .env

32. Error: 429 rate_limit_error

⚠️ 원인
분당 RPM·일별 RPD 한도를 초과한 경우입니다.
💡 해결 방법
  • exponential backoff를 구현하세요 (별책부록 6편 참고)
  • 사용량을 줄이거나
  • Tier 1 → Tier 2로 자동 상향됩니다 (사용량이 충분히 쌓이면)

33. Error: 500 server_error

⚠️ 원인
Anthropic 서버가 일시적으로 오류 상태입니다.
💡 해결 방법

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이 제대로 작동하지 않는 경우
🎉 해결 방법
  1. console.anthropic.com에서 비용을 분석하세요
  2. prompt_cache_hit_rate를 확인하세요 (90% 이상 권장)
  3. system prompt에 caching이 적용되어 있는지 확인하세요

40. Streaming 도중 끊김

⚠️ 원인
네트워크가 일시적으로 끊긴 경우입니다.
💻 해결 — try/except로 안전하게 처리
try:
    async for chunk in stream:
        # 청크 처리
        pass
except Exception:
    # 마지막까지 처리된 내용을 그대로 사용
    pass
E systemd·pm2 에러 (41~50번) 🔗

41. 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%

⚠️ 원인
봇 코드에서 무한 루프가 발생 중입니다.
💡 해결 방법
  1. pm2 stop 봇으로 즉시 중단하세요
  2. 코드에서 무한 루프 구간을 찾아 수정하세요
  3. 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 공식 문서를 참고하세요
  • 새 에러를 만나면 위 패턴에서 가장 가까운 항목을 찾아 적용해 보세요