CORS 에러 해결 — 콘솔 메시지로 원인 진단하기

CORS 에러는 프런트 개발자가 가장 자주, 그리고 가장 오해하며 만나는 에러입니다. 핵심부터 짚으면, CORS는 브라우저가 강제하는 규칙이고 에러는 서버가 아니라 브라우저가 띄우는 것입니다. curl 로는 멀쩡히 되는데 브라우저에서만 막히는 이유가 여기 있습니다.

콘솔 에러부터 정확히 읽는다

OUTPUT

Access to fetch at 'https://api.example.com/users' from origin
'https://app.example.com' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.

이 메시지는 "서버 응답에 Access-Control-Allow-Origin 헤더가 없어서 브라우저가 응답을 차단했다"는 뜻입니다. 요청 자체는 서버에 도달했고 응답도 왔지만, 브라우저가 JS에 넘겨주기 전에 막은 것입니다.

응답 헤더부터 확인

서버가 실제로 어떤 CORS 헤더를 주는지 봅니다.

로컬 또는 서버

curl -i -H "Origin: https://app.example.com" https://api.example.com/users

응답에 Access-Control-Allow-Origin: https://app.example.com 이 있어야 합니다. 없거나 다른 origin이면 브라우저가 차단합니다.

증상별 원인

콘솔 메시지	원인	해결
`No 'Access-Control-Allow-Origin' header`	서버가 CORS 헤더를 안 줌	서버에서 요청 origin 허용
`does not match the supplied origin`	허용 origin이 다름	origin 값 정확히 일치시키기
`Response to preflight request doesn't pass`	preflight(OPTIONS) 실패	OPTIONS에도 CORS 헤더 응답
`must not be the wildcard '*' when credentials`	쿠키+와일드카드 충돌	`*` 대신 정확한 origin 명시

preflight를 이해해야 풀린다

PUT/DELETE 이거나 커스텀 헤더(Authorization 등)가 붙으면, 브라우저는 본 요청 전에 OPTIONS 로 사전 요청(preflight) 을 보냅니다. 이게 통과해야 본 요청이 나갑니다.

로컬 또는 서버

curl -i -X OPTIONS \
  -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: PUT" \
  -H "Access-Control-Request-Headers: authorization" \
  https://api.example.com/users

응답에 Access-Control-Allow-Methods 와 Access-Control-Allow-Headers 가 요청한 값을 포함해야 합니다. 쿠키·인증을 함께 보낸다면 Access-Control-Allow-Credentials: true 가 필요하고, 이때는 Allow-Origin 에 와일드카드 * 를 쓸 수 없습니다.

점검 체크리스트

로컬 또는 서버

# 1) 본 요청 응답에 Allow-Origin이 오는가
curl -i -H "Origin: https://app.example.com" https://api.example.com/users

# 2) preflight(OPTIONS)가 통과하는가
curl -i -X OPTIONS -H "Origin: https://app.example.com" \
  -H "Access-Control-Request-Method: PUT" https://api.example.com/users

# 3) credentials 사용 시 와일드카드를 쓰지 않았는가
#    Allow-Origin은 정확한 origin, Allow-Credentials: true

브라우저 네트워크 탭에서 막힌 요청을 클릭해 응답 헤더를 직접 확인하는 습관이, 추측을 끝내는 가장 빠른 길입니다.

CORS·preflight·헤더를 직접 요청해보고 진단하는 실습은 네트워크 트랙에서 회원가입 없이 무료로 할 수 있습니다.