로컬에선 작동하는데 서버에서만 터질 때

"로컬에선 문제가 없는데 서버에서만 계속 오류가 난다"는 상황은 개발할 때 가장 답답한 경우 중 하나다. 이런 문제는 보통 환경 차이 때문인데, 디스크, 권한, 프로세스 포트 등 여러 원인이 있을 수 있다. 어디부터 확인해야 하는지 체계적으로 정리했다.

서버 상태 확인

가장 먼저 서버의 기본 상태를 파악한다.

sudo ss -lntp
df -h
sudo journalctl -n 80

• ss -lntp: 현재 리스닝 중인 포트와 프로세스 확인
• df -h: 디스크 용량 (특히 root 파티션이 가득 찬 경우가 많음)
• journalctl: 최근 시스템 로그 확인

디스크 용량이 부족하면 애플리케이션이 로그를 쓸 수 없거나 메모리를 할당할 수 없어서 예상 못한 오류가 난다.

권한 확인

애플리케이션 프로세스가 필요한 파일이나 디렉토리에 접근 권한이 있는지 확인한다.

ls -la /path/to/app

특히 로그 디렉토리, 업로드 디렉토리, 데이터베이스 파일 등의 권한이 맞는지 체크한다. 로컬에서는 root로 실행해도 상관없지만, 서버에서는 애플리케이션 유저가 접근할 수 있는 권한이 있어야 한다.

환경 변수 확인

서버에 배포된 .env 파일이 로컬과 다를 수 있다.

• API 엔드포인트
• 데이터베이스 연결 문자열
• 외부 서비스 토큰

이런 설정 중 하나라도 빠지거나 잘못되면, 로컬에서 테스트한 것과 완전히 다른 결과가 나온다.

프로세스와 포트

같은 포트를 사용하는 다른 프로세스가 있는지 확인한다. 또는 애플리케이션이 실제로 실행 중인지 확인한다.

sudo ps aux | grep <app-name>

최종 확인

1. 서버에서 같은 오류가 반복되는지 확인
2. 로그에서 구체적인 오류 메시지 찾기
3. 공개 URL이나 실제 화면에서 문제가 해결되었는지 테스트

문제를 찾았으면, 그 원인이 앞으로도 반복되지 않도록 자동화나 모니터링을 설정해두는 것이 좋다.