[트러블슈팅] 로컬 환경 이메일 발송 스킵 조건 오류 해결

TROUBLESHOOTING

로컬 환경에서 이메일 발송 스킵 미적용으로 인한 500 오류

목차

• 1. 발생 배경
• 2. 문제
• 3. 원인 파악 과정
• 4. 해결
• 5. 참고
• 6. 배운 점

1. 발생 배경

이메일 인증 기능을 구현한 뒤 Postman으로 /auth/email/send API를 처음 테스트하는 과정에서 500 오류가 발생했다.

 

로컬 환경에서는 실제 Gmail SMTP로 이메일을 발송하지 않고, 인증 코드를 콘솔 로그로 확인하도록 처리하려고 했다. 하지만 의도와 달리 로컬 테스트 중 실제 Gmail SMTP 인증이 시도되면서 오류가 발생했다.

이번 문제의 핵심은 이메일 발송 로직 자체보다, 현재 실행 중인 Spring Profile과 이메일 발송 스킵 조건이 맞지 않았다는 점이다.

2. 문제

이메일 인증 코드 발송 API를 호출하자 서버에서 500 오류가 발생했다. 원인은 로컬 환경에서 실제 Gmail SMTP 인증을 시도하다가 인증에 실패한 것이었다.

org.springframework.mail.MailAuthenticationException: Authentication failed
Caused by: jakarta.mail.AuthenticationFailedException: 535-5.7.8 Username and Password not accepted.

Postman에서 /auth/email/send API를 호출했을 때 발생한 500 오류 응답이다.

3. 원인 파악 과정

1. 500 오류가 발생했지만 콘솔에 상세 로그가 출력되지 않아 원인 파악이 어려웠다.
2. GlobalExceptionHandler에 log.error를 추가한 뒤 다시 테스트했다.
3. 스택트레이스를 통해 MailAuthenticationException이 발생한 것을 확인했다.
4. activeProfile 로그를 추가해 실제 실행 프로파일이 dev로 잡힌 것을 확인했다.
5. 메일 발송 스킵 조건을 수정한 뒤 문제가 해결되었다.

1단계 - 로그 미출력으로 원인 파악 지연

처음에는 500 오류가 발생했지만 콘솔에 스택트레이스가 출력되지 않았다. 원인은 GlobalExceptionHandler의 Exception 핸들러에 log.error가 없었기 때문이다.

서버 내부 오류가 발생했을 때 로그가 남지 않으면, 클라이언트에서는 단순히 500 응답만 확인할 수 있어 실제 원인을 찾기 어렵다.

2단계 - activeProfile 불일치

로컬 환경에서 메일 발송을 스킵하기 위해 처음에는 activeProfile이 local인지 여부를 기준으로 분기했다.

초기에는 activeProfile이 local일 때만 이메일 발송을 스킵하도록 작성했다.

하지만 실제 실행 프로파일은 local이 아니라 dev로 잡혀 있었다. 그래서 스킵 분기를 타지 않고 실제 메일 발송 로직이 실행되었다.

[DEBUG] activeProfile: dev
local이어야 스킵되는데 dev로 잡혀 실제 Gmail SMTP 발송을 시도했다.

4. 해결

1. GlobalExceptionHandler에 log.error 추가

먼저 서버 내부 오류가 발생했을 때 원인을 빠르게 확인할 수 있도록 GlobalExceptionHandler에 log.error를 추가했다.

 

이 수정 이후 500 오류 발생 시 콘솔에서 스택트레이스를 확인할 수 있었고, 실제 원인이 MailAuthenticationException이라는 것을 파악할 수 있었다.

[GlobalExceptionHandler] 서버 내부 오류 발생
org.springframework.mail.MailAuthenticationException: Authentication failed
    at ...
Caused by: jakarta.mail.AuthenticationFailedException: 535-5.7.8 ...
    at ...

2. 스킵 조건을 prod일 때만 발송하도록 변경

기존 방식은 local이 아닐 때 메일을 발송하는 구조였다. 하지만 실제 로컬 실행 프로파일이 dev로 잡히면서, 개발 환경에서도 실제 메일 발송이 시도되는 문제가 있었다.

그래서 특정 개발 프로파일을 제외하는 방식 대신, 운영 프로파일인 prod일 때만 실제 메일을 발송하도록 조건을 변경했다.

activeProfile이 prod일 때만 실제 이메일을 발송하고, 그 외 환경에서는 인증 코드를 로그로 출력하도록 변경한 코드다.

이메일 발송 스킵 조건을 수정한 뒤 /auth/email/send API가 정상 응답한 화면이다.

로컬 환경에서는 실제 이메일 발송 대신 인증 코드가 콘솔 로그로 출력되는 것을 확인했다.

결과적으로 운영 환경이 아닌 경우에는 실제 Gmail SMTP 인증을 시도하지 않게 되었고, 로컬에서는 인증 코드를 로그로 확인하면서 이메일 인증 흐름을 테스트할 수 있게 되었다.

5. 참고

• GlobalExceptionHandler에는 log.error를 포함해야 500 오류 원인을 빠르게 파악할 수 있다.
• 환경별 분기는 local, dev처럼 특정 프로파일을 하나씩 명시하는 것보다 prod만 명시하는 방식이 더 안전하다.
• 로컬 환경에서 인증 코드는 콘솔 로그로 확인하도록 처리하면 개발 중 SMTP 인증 정보 없이 테스트할 수 있다.

6. 배운 점

로컬 환경 분기 조건은 local이 아니면보다 prod일 때만으로 작성하는 것이 더 안전하다. 프로파일이 추가되거나 변경되는 상황에서도 운영 환경이 아닌 경우 실제 외부 서비스 호출을 막을 수 있기 때문이다.

정리하면, 개발 환경에서는 외부 메일 발송을 기본적으로 막고, 운영 환경에서만 실제 발송되도록 조건을 제한하는 방식이 더 안전하고 유지보수하기 쉽다.