'Request header field x-auth-token is not allowed by Access-Control-Allow-Headers' 에러의 원인과 서버 허용 목록 설정을 시뮬레이션으로 확인하세요.
시나리오 프리셋
요청 — 브라우저(페이지) 쪽
Method
Content-Type
커스텀 헤더
Access-Control-Request-Headers: content-type, x-auth-token
응답 — 서버가 보내는 헤더
Access-Control-Allow-Origin
Access-Control-Allow-Methods
Access-Control-Allow-Headers
요청에 필요한 헤더 + 자주 쓰는 값 — 클릭으로 토글
브라우저 처리 단계
페이지에서 fetch 요청 발생
단순 요청이 아님 — OPTIONS 프리플라이트 필요
OPTIONS 프리플라이트 요청 전송
OPTIONS /data HTTP/1.1 Origin: https://myapp.example.com Access-Control-Request-Method: POST Access-Control-Request-Headers: content-type, x-auth-token
서버의 프리플라이트 응답 도착
HTTP/1.1 204 No Content Access-Control-Allow-Origin: https://myapp.example.com Access-Control-Allow-Methods: GET, POST, PUT Access-Control-Allow-Headers: content-type
Allow-Origin이 출처와 일치 — 통과
요청 메서드가 Allow-Methods에 포함 — 통과
요청 헤더가 Allow-Headers에 없음x-auth-token
credentials 미사용 — 검사 생략
브라우저가 응답을 차단하고 fetch를 reject
브라우저 콘솔
✕ Access to fetch at 'https://api.example.com/data' from origin 'https://myapp.example.com' has been blocked by CORS policy: Request header field content-type is not allowed by Access-Control-Allow-Headers in preflight response.
(index):1
값을 바꾸면 아래 단계가 즉시 다시 계산됩니다. 'credentials + *' 시나리오에서 와일드카드가 왜 막히는지 확인해 보세요.
Authorization·X-Api-Key 같은 커스텀 헤더나 application/json Content-Type은 safelist 밖이라 프리플라이트의 Access-Control-Request-Headers에 실립니다. 서버의 Access-Control-Allow-Headers가 그 목록을 모두 커버하지 못하면 'Request header field X is not allowed'로 차단됩니다.
흔한 함정은 대소문자가 아니라 누락입니다 — 헤더 이름은 대소문자를 가리지 않지만, content-type까지 허용 목록에 넣어야 한다는 사실을 놓치는 경우가 많습니다. Authorization만 적어놓고 content-type이 빠지면 역시 실패합니다.
시뮬레이터에서 커스텀 헤더 이름을 바꿔가며 Allow-Headers 텍스트를 수정해 보세요. 요청 측 파란 박스의 Access-Control-Request-Headers가 서버 응답에 어떻게 대응되는지 바로 보입니다. CORS 시뮬레이터에서 다른 시나리오도 같은 설정으로 비교해 보세요.