CORS 에러가 났는데 서버 로그에는 요청이 안 보이는 이유

문제 발생

프론트엔드에서 API를 호출했는데 브라우저 콘솔에 CORS 에러가 떴습니다. 그런데 백엔드 서버 로그를 확인해보니 해당 요청 자체가 아예 도달하지 않은 것처럼 기록이 없었습니다.

원인 분석

브라우저는 특정 조건을 만족하는 cross-origin 요청(다른 출처로 보내는 요청) 앞에 preflight 요청을 자동으로 먼저 보냅니다. Content-Type: application/json으로 body가 있는 POST 요청이나, 커스텀 헤더(Authorization 등)를 포함한 요청은 대부분 preflight 대상입니다.

preflight는 OPTIONS 메서드로 보내며, 실제 요청과는 별개의 HTTP 요청입니다. 서버가 이 OPTIONS 요청에 대해 "이 출처(origin), 이 메서드, 이 헤더를 허용한다"는 응답(Access-Control-Allow-* 헤더들)을 제대로 주지 않으면, 브라우저는 실제 요청(POST 등)을 아예 보내지 않고 즉시 실패시킵니다. 그래서 서버 로그에는 실패한 흔적조차 안 남는 경우가 많습니다 — 실제 요청이 서버에 도달하기 전에 브라우저가 차단했기 때문입니다.

해결 방안

1. 서버가 OPTIONS 메서드에 대한 라우트를 별도로 처리하거나, 프레임워크의 CORS 미들웨어가 자동으로 처리하도록 설정합니다.
2. preflight 응답에 최소한 다음 헤더가 필요합니다.

Access-Control-Allow-Origin: https://example.com  (또는 정확한 허용 출처)
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

3. 인증 정보(쿠키 등)를 함께 보내야 한다면 Access-Control-Allow-Credentials: true가 필요하고, 이 경우 Access-Control-Allow-Origin은 *를 쓸 수 없습니다 — 정확한 출처를 명시해야 합니다.
4. 브라우저 개발자 도구의 Network 탭에서 실제 요청 메서드가 OPTIONS인 요청이 먼저 나가는지, 그 응답이 200인지, 응답 헤더에 필요한 Access-Control-* 값이 있는지 확인하는 것이 가장 빠른 디버깅 방법입니다.
5. 단순 GET 요청이면서 커스텀 헤더가 없는 경우("simple request") 등 preflight가 아예 없는 요청도 있으므로, 지금 겪는 CORS 에러가 preflight 실패인지 실제 요청 응답의 CORS 헤더 누락인지부터 구분해야 합니다.

공식 문서

• MDN: Cross-Origin Resource Sharing (CORS)
• MDN: CORS-preflight request