500 Internal Server Error 진단

Problem

사이트 접속 시 최종 응답 코드가 500 Internal Server Error로 반환됩니다.

Symptoms

• HTTP Check에서 최종 코드가 500입니다.
• 원인에 대한 설명 없이 일반적인 오류 페이지만 나옵니다.
• 항상 발생하거나, 특정 경로에서만, 또는 부하 시에만 나타날 수 있습니다.

500이 실제로 뜻하는 것

RFC 9110(§15.6.1)은 500을 “서버가 요청을 처리하지 못하게 만든 예기치 못한 상황을 만난 것”으로 정의합니다. 더 구체적인 5xx 코드가 없을 때 오리진이 내놓는 포괄 코드입니다. 핵심 구분은 이렇습니다 — 500은 애플리케이션 자신의 코드가 실패한 것이고, 502·503·504는 그 앞단의 게이트웨이나 프록시가 개입한 것입니다. 500은 요청이 애플리케이션까지 도달했고, 거기서 깨졌다는 뜻입니다.

그래서 페이지는 쓸모없고 로그가 전부입니다. 서버가 스택 트레이스를 일부러 외부에 감추고 있는 것입니다.

Top 3 Causes

1. 미처리 애플리케이션 예외 - 프레임워크가 잡지 못한 오류를 코드가 던졌습니다. null 참조, 쿼리 실패, 잘못된 타입 등. 가장 흔한 500입니다.
2. 서버·환경 설정 오류 - 깨진 .htaccess, 잘못된 파일 권한, 누락된 모듈이나 환경변수, 실패한 배포 때문에 앱이 요청을 정상적으로 시작하지 못합니다.
3. 리소스 고갈 - 프로세스가 메모리를 소진했거나, 커넥션 풀 한도에 걸렸거나, 파일 디스크립터가 바닥나 처리 도중 요청이 죽습니다.

Diagnose with DechoNet

• HTTP Check로 최종 코드가 정말 500인지, 게이트웨이 502/503/504가 아닌지 확인합니다.
• Port Check로 오리진이 실제로 연결을 받고 있는지 확인해, 죽은 프로세스가 500처럼 보이는 경우를 배제합니다.
• DNS Lookup으로 트래픽이 의도한 오리진에 닿고 있는지(낡거나 잘못된 호스트가 아닌지) 확인합니다.

Resolution Checklist

• 서버·애플리케이션 에러 로그를 엽니다 — 실제 원인은 500 페이지가 아니라 여기 있습니다.
• 특정 URL 하나로 재현하고, 전 경로인지 일부 경로인지 기록합니다.
• 가장 최근 배포·설정 변경을 확인하고 롤백해 테스트합니다.
• 앱 기동에 필요한 파일 권한, 필수 모듈, 환경변수를 검증합니다.
• 부하 시 메모리, DB 커넥션, 파일 디스크립터 한도를 관찰합니다.
• 수정 후 HTTP Check를 다시 실행해 500이 사라졌는지 확인합니다.

When to Escalate

• 로그가 인프라가 아닌 비즈니스 로직의 예외를 가리키면 애플리케이션 담당자에게 넘깁니다.
• 부하 시에만 500이 나타나면 플랫폼 팀과 함께 스케일링, 커넥션 풀, 리소스 한도를 점검합니다.