Kord/Docs/Troubleshooting/handleLeave_ghost_channel.md

임시 음성 채널 미삭제 및 유령 방 버그 (handleLeave)

체인지로그 (Changelog)

• 2026-03-27: 문서 작성

본문 (Body)

현상 (Symptom)

사용자가 임시 채널에서 퇴장해도 채널이 지워지지 않고 그대로 남는 현상 발생.

원인 (Cause)

1. 음악 봇 잔류 문제: 디스코드 채널에 봇(Bot) 멤버가 남아있을 경우 channel.members.size === 0 조건을 충족하지 못해 삭제 로직이 작동하지 않음.
2. 에러 핸들링 누락으로 인한 DB 고립: 50013 권한 부족 등의 이유로 디스코드 서버에서 채널 삭제(channel.delete())가 실패했을 때, 에러를 무시하고 DB 레코드만 삭제해버림. 이로 인해 디스코드상에는 삭제 불가능한 유령 방이 남게 되고 봇은 이를 영원히 추적하지 못하게 됨.

해결 (Solution)

1. humanCount 변수를 도입하여 !user.bot인 멤버(실제 사용자)가 0명일 때만 지워지도록 로직 수정.
2. try-catch 스코프 내부에서 디스코드 API 삭제 명령이 실패할 경우, DB 삭제 처리(prisma.tempVoiceChannel.delete)를 중단하고 터미널에 에러 로그를 명확히 남겨 무결성을 유지하도록 예외 처리.