CORS 오류가 발생하는 이유 8가지와 서버 설정 확인법

스크립트에서 다른 도메인의 데이터를 불러오려 하면 Console에 출처 관련 붉은 메시지가 뜨고 요청이 실패합니다. CORS 오류는 서버가 고장 난 것이 아니라, 브라우저가 안전을 위해 응답을 읽지 못하도록 막은 결과입니다.

서버는 대부분 정상적으로 응답을 보냈습니다. 다만 그 응답에 “이 출처가 읽어도 된다”는 허가 헤더가 없어서 브라우저가 내용을 코드에 전달하지 않은 것입니다. 그래서 서버 로그에는 성공으로 남고 브라우저에서만 실패로 보입니다. 이 글은 CORS 오류가 생기는 조건과 확인 순서를 정리합니다.

서버 종류별 헤더 추가 위치

아파치에서는 헤더 모듈을 사용해 응답에 허용 출처 항목을 붙입니다. 특정 경로에만 적용하려면 해당 위치 블록 안에 설정을 넣으면 됩니다. 설정을 바꾼 뒤에는 서버가 설정을 다시 읽어야 반영됩니다.

엔진엑스에서는 위치 블록 안에서 헤더 추가 지시어를 사용합니다. 확인용 요청에 대한 응답을 별도로 처리해 주어야 하는 경우가 많아, 요청 방식에 따라 분기하는 설정이 함께 들어갑니다.

워드프레스에서는 코드로 헤더를 붙이거나 전용 플러그인을 사용할 수 있습니다. 다만 앞단에 캐시가 있으면 헤더가 캐시된 응답에 포함되지 않는 경우가 있어, 캐시 설정을 함께 확인해야 합니다.

클라우드 환경에서는 앞단의 게이트웨이나 로드 밸런서가 헤더를 관리하기도 합니다. 원본 서버에 설정을 넣었는데 반영되지 않는다면 앞단 설정을 확인해 보십시오.

가정 예시 — 실제 항목명은 서버 버전에 따라 다를 수 있음

CORS 오류를 없애려고 모든 출처를 허용하면 당장은 화면이 동작하지만 보안 위험이 함께 열립니다. 필요한 출처만 목록으로 적어 두는 편이 안전합니다.

설정을 여러 계층에서 동시에 하고 있으면 헤더가 두 번 붙어 오히려 요청이 거부되기도 합니다. 어느 계층에서 헤더를 붙일지 한 곳으로 정해 두는 편이 좋습니다.

브라우저 밖에서 요청을 재현하기

같은 요청을 터미널에서 실행해 보면 서버가 실제로 어떤 응답을 주는지 그대로 볼 수 있습니다. 브라우저의 차단이 없으므로 응답 본문과 헤더를 모두 확인할 수 있습니다.

여기서 정상 응답이 오고 허용 헤더만 없다면, 서버는 잘 동작하고 있고 설정만 추가하면 되는 상태입니다. 반대로 여기서도 실패하면 CORS 오류가 아니라 다른 문제입니다.

개발자 도구에서 요청을 오른쪽 버튼으로 눌러 명령어 형태로 복사하면 헤더까지 그대로 재현할 수 있어 편리합니다.

브라우저 밖에서 같은 요청을 보내면 서버가 어떤 헤더를 돌려주는지 그대로 확인할 수 있습니다. 아래는 출처를 지정해 사전 요청과 본 요청을 각각 보내 보는 예시입니다.

1
2
3
4
5
6

curl -i -X OPTIONS https://api.example.com/items \
  -H 'Origin: https://app.example.com' \
  -H 'Access-Control-Request-Method: POST'

curl -i https://api.example.com/items \
  -H 'Origin: https://app.example.com'

응답에 허용 출처 헤더가 보이지 않는다면 서버가 아직 설정되지 않은 것입니다. 헤더는 있는데 값이 다른 주소라면 목록에 현재 화면 주소를 추가해야 합니다.

터미널 요청은 성공하는데 브라우저에서만 CORS 오류가 난다면 이는 정상적인 동작입니다. 브라우저만 이 규칙을 적용하기 때문입니다.

보안 관점에서 함께 볼 것

허용 출처를 모든 곳으로 열어 두면 누구나 그 응답을 읽을 수 있게 됩니다. 공개 데이터라면 문제가 없지만, 사용자별 정보를 다루는 경로에는 적절하지 않습니다.

필요한 출처만 목록으로 관리하고, 요청이 들어올 때 그 목록과 대조해 허용 여부를 정하는 방식이 안전합니다. 목록은 코드가 아니라 설정 값으로 분리해 두면 관리가 쉽습니다.

허용 방식과 허용 헤더도 최소한으로 유지하는 편이 좋습니다. 필요하지 않은 항목까지 열어 두면 의도하지 않은 요청까지 통과합니다.

확인 순서를 짧게 정리하면

먼저 Console 메시지를 끝까지 읽어 어느 조건이 어긋났는지 확인합니다. 그다음 Network에서 확인용 요청의 유무와 응답을 봅니다. 마지막으로 응답 헤더에 허용 항목이 실제로 붙어 있는지 확인합니다.

세 단계면 CORS 오류의 원인은 거의 항상 특정됩니다. 이후 조치는 서버 설정 한 곳에서 끝나는 경우가 대부분입니다.

같은 출처처럼 만드는 우회 구성

브라우저 입장에서 출처가 같아지도록 구조를 바꾸면 규칙 자체가 적용되지 않습니다. 대표적인 방법은 같은 도메인의 특정 경로로 들어온 요청을 서버가 대신 외부로 전달하고 결과만 돌려주는 구성입니다.

이 방식은 외부 서비스의 설정 권한이 없을 때 특히 유용합니다. 인증 키를 브라우저에 노출하지 않아도 되므로 보안 측면에서도 이점이 있습니다.

다만 서버를 한 단계 더 거치므로 응답 시간이 늘고 서버 부하가 증가합니다. 호출 빈도가 높다면 결과를 잠시 보관해 두는 방식을 함께 검토하는 편이 좋습니다.

정적 파일이라면 아예 내 서버로 복사해 두는 방법도 있습니다. 글꼴이나 아이콘처럼 자주 바뀌지 않는 자원에 적합합니다.

개발 단계에서는 화면과 API가 서로 다른 포트에서 동작하기 때문에 매번 CORS 오류를 만나게 됩니다. 개발 서버의 프록시 기능을 쓰면 요청이 같은 출처를 거쳐 나가므로 설정을 바꾸지 않고도 확인을 이어 갈 수 있습니다.

운영 환경에서는 같은 도메인 아래 경로만 나누어 배치하는 구성이 자주 쓰입니다. 화면은 루트에, API는 하위 경로에 두면 출처가 같아져 별도 헤더 설정이 필요 없습니다.

다만 우회 구성은 설정을 감추는 것이지 없애는 것이 아닙니다. 나중에 도메인을 분리하면 같은 문제가 다시 나타나므로 구조를 문서로 남겨 두는 편이 좋습니다.

문제를 기록으로 남기기

원인을 찾았다면 어떤 조건에서 막혔는지 한 줄로 남겨 두십시오. 허용 헤더 부재인지, 확인용 요청 실패인지, 인증 정보 조합 문제인지만 적어도 다음에 같은 상황을 훨씬 빨리 정리할 수 있습니다.

외부 서비스를 새로 연동할 때는 허용 목록 등록 절차를 먼저 확인하는 습관이 도움이 됩니다. 개발이 끝난 뒤 CORS 오류로 막히면 일정이 늦어지는 경우가 많습니다.

기록에는 화면 주소와 요청 주소를 반드시 함께 적어 둡니다. 둘 중 하나만 있으면 나중에 어느 조합에서 CORS 오류가 났는지 다시 확인해야 합니다.

Console 메시지 원문과 Network 탭의 응답 헤더를 함께 남겨 두면 서버 담당자에게 전달할 내용이 그대로 완성됩니다.

메시지 문구로 원인을 가려내기

Console에 출력되는 문장은 조건마다 다릅니다. 허용 출처 항목이 아예 없다는 문장, 값이 요청한 출처와 다르다는 문장, 인증 정보를 포함한 요청에서는 기호를 쓸 수 없다는 문장이 각각 구분되어 나옵니다.

확인용 요청이 정상 응답을 받지 못했다는 문장도 있습니다. 이 경우 본 요청은 시도조차 되지 않으므로, 서버가 그 요청 방식에 응답하도록 설정을 먼저 손봐야 합니다.

허용 헤더 목록에 요청한 헤더가 없다는 문장이 보이면, 코드에서 붙인 사용자 정의 헤더 이름을 서버 설정에 추가하면 됩니다.

문장을 그대로 읽는 것만으로 조치 위치가 정해지므로, CORS 오류를 만나면 메시지를 끝까지 읽는 습관이 가장 큰 도움이 됩니다.

정리하며 기억할 기준

이 규칙은 사이트를 불편하게 만들려는 장치가 아니라, 다른 사이트가 내 로그인 상태를 이용해 데이터를 빼가지 못하도록 막는 보호 장치입니다. 우회보다 올바른 허용 설정을 찾는 방향이 맞습니다.

출처 세 요소를 비교하고, 확인용 요청의 응답을 보고, 허용 헤더의 존재와 값을 확인하는 세 단계를 순서대로 밟으면 대부분의 사례가 정리됩니다.

연동 전에 확인해 두면 좋은 항목

외부 서비스를 붙이기 전에 문서에서 허용 출처 등록 방법과 지원하는 요청 방식을 먼저 확인하십시오. 대부분의 서비스는 관리 화면에 등록 항목을 제공합니다.

테스트용 도메인과 운영 도메인을 모두 등록해 두어야 합니다. 개발 중에는 정상이었는데 배포 후 CORS 오류가 나는 사례의 상당수가 운영 도메인 미등록 때문입니다.

외부 API를 연동하기 전에 아래 항목을 확인해 두면 개발 도중에 막히는 일이 줄어듭니다.

• API가 다른 출처 요청을 허용하는지, 허용 목록 방식인지
• 인증 정보를 함께 보내야 하는지
• 사용자 지정 헤더가 필요한지
• 사전 요청 결과가 얼마나 저장되는지
• 설정을 바꿀 권한이 우리 쪽에 있는지

마지막 항목이 특히 중요합니다. 설정 권한이 없는 외부 API라면 CORS 오류는 우리 서버를 거쳐 요청하는 구성으로만 풀 수 있습니다.

출처가 다르다는 판단 기준

브라우저는 프로토콜, 도메인, 포트 세 가지가 모두 같아야 같은 출처로 봅니다. 하나라도 다르면 다른 출처이며, 이때부터 교차 출처 규칙이 적용됩니다.

같은 회사 도메인이라도 앞에 붙는 이름이 다르면 다른 출처입니다. http와 https도 다른 출처로 취급되며, 포트 번호가 다르면 역시 별개입니다. 이 기준을 모르면 CORS 오류가 왜 나는지 이해하기 어렵습니다.

주소창에 직접 입력해 열면 잘 열리는데 코드에서만 실패하는 이유도 여기에 있습니다. 주소창 접속은 문서 이동이라 이 규칙의 대상이 아닙니다.

가정 예시 — 경로는 출처 판단에 포함되지 않습니다

세 가지 중 하나만 달라도 다른 출처입니다. 눈으로는 같은 사이트처럼 보여도 포트나 www 유무가 다르면 CORS 오류가 나타납니다.

주소를 하나로 통일할 수 있다면 설정을 늘리지 않고도 문제가 사라집니다. 리다이렉션으로 www 유무를 맞추는 것만으로 해결되는 경우도 많습니다.

허가 헤더가 없을 때

서버가 응답에 허용 출처 헤더를 붙이지 않으면 브라우저는 내용을 감춥니다. 이 헤더에는 허용할 출처 주소를 적거나 모든 출처를 뜻하는 기호를 넣습니다.

해결은 서버 쪽에서 이루어져야 합니다. 브라우저 설정이나 코드 수정으로는 우회할 수 없습니다. 외부 서비스라면 그 서비스가 제공하는 허용 목록 설정에 내 도메인을 등록해야 합니다.

모든 출처를 허용하는 설정은 편리하지만 인증 정보를 함께 보내는 요청에서는 사용할 수 없습니다. 이 경우 허용할 출처를 명시적으로 적어야 합니다.

사전 요청이 실패하는 경우

브라우저는 일부 요청을 보내기 전에 확인용 요청을 먼저 보냅니다. 서버가 이 확인 요청에 제대로 답하지 않으면 본 요청은 아예 시도되지 않습니다.

Network 탭을 보면 실제 요청 앞에 다른 방식의 요청이 하나 더 있는 것이 보입니다. 이 요청이 실패했다면 CORS 오류의 원인은 여기에 있습니다.

서버는 이 확인 요청에 허용 방식과 허용 헤더 목록을 함께 답해야 합니다. 사용자 정의 헤더를 붙였다면 그 이름이 허용 목록에 들어 있어야 합니다.

사전 요청은 본 요청을 보내도 되는지 미리 물어보는 절차입니다. 브라우저가 알아서 보내기 때문에 코드에는 나타나지 않지만 Network 탭에는 OPTIONS 요청으로 남습니다.

이 요청이 실패하면 본 요청은 아예 보내지지 않습니다. 서버 로그에 본 요청 기록이 없는데 화면에서는 CORS 오류가 보인다면 사전 요청 단계에서 끊긴 것입니다.

서버가 OPTIONS 메서드를 처리하도록 되어 있는지부터 확인해야 합니다. 인증을 요구하는 구성이라면 사전 요청에는 인증 정보가 실리지 않으므로 예외로 두어야 합니다.

인증 정보를 함께 보낼 때

쿠키나 인증 헤더를 함께 보내는 요청은 규칙이 더 엄격합니다. 서버가 인증 정보 허용 항목을 참으로 지정해야 하고, 허용 출처에 기호 대신 정확한 주소를 적어야 합니다.

클라이언트 쪽에서도 인증 정보를 포함하도록 명시해야 합니다. 한쪽만 설정하면 요청은 나가지만 응답을 읽지 못하는 상태가 됩니다.

이 조합에서 발생하는 CORS 오류는 메시지가 구체적으로 나옵니다. Console 메시지를 끝까지 읽으면 어느 조건이 어긋났는지 문장으로 확인할 수 있습니다.

리다이렉션이 끼어들 때

요청이 다른 주소로 넘어가면 그 과정에서도 허가 헤더가 유지되어야 합니다. 중간 단계에서 헤더가 빠지면 최종 응답이 정상이어도 브라우저는 차단합니다.

주소 끝의 슬래시 유무 때문에 리다이렉션이 발생하는 경우가 흔합니다. 요청 주소를 서버가 기대하는 형태로 정확히 맞추면 불필요한 단계를 없앨 수 있습니다.

http로 요청했다가 https로 넘어가는 구성도 같은 문제를 만듭니다. 처음부터 https로 요청하는 편이 안전합니다.

요청 주소가 다른 주소로 넘어가면 브라우저는 최종 응답만이 아니라 중간 응답도 함께 확인합니다. 중간 응답에 허용 헤더가 없으면 그 지점에서 막힙니다.

www 유무나 끝의 슬래시 때문에 넘어가는 경우가 많으므로, 요청 주소를 최종 형태로 맞춰 두면 이 문제는 대부분 사라집니다.

개발 환경에서 자주 겪는 상황

로컬 개발 서버와 API 서버의 포트가 다르면 출처가 달라져 CORS 오류가 발생합니다. 개발 서버의 대리 요청 기능을 사용하면 브라우저 입장에서는 같은 출처가 되어 문제가 사라집니다.

파일을 직접 열어 실행하는 경우에도 출처가 없는 상태로 취급되어 대부분의 요청이 차단됩니다. 간단한 로컬 서버를 띄워 주소로 접속하는 편이 좋습니다.

브라우저 보안 기능을 꺼서 확인하는 방법도 있지만, 실제 환경에서는 해결되지 않으므로 임시 확인용으로만 쓰는 편이 맞습니다.

CORS 오류를 좁히는 점검 순서

아래 순서는 위에서부터 차례대로 확인하도록 정리한 것입니다. 앞 단계에서 원인이 드러나면 뒤 단계는 건너뛰어도 됩니다.

1단계 · Console 메시지 문구 확인

브라우저는 어떤 조건에서 막았는지를 문장으로 남깁니다. 허용 헤더가 없다는 문구인지, 값이 다르다는 문구인지에 따라 대응이 달라집니다.

메시지를 그대로 기록해 두면 서버 담당자에게 전달할 때도 설명이 짧아집니다.

2단계 · 두 주소를 나란히 비교

화면 주소와 요청 주소를 프로토콜, 도메인, 포트 단위로 나누어 비교합니다. 어느 항목이 다른지 정하는 것만으로 확인 범위가 좁아집니다.

개발 환경에서는 포트만 다른 경우가 대부분입니다.

3단계 · 사전 요청 여부 확인

Network 탭에 OPTIONS 요청이 먼저 보이는지 확인합니다. 사전 요청이 실패하면 본 요청은 아예 보내지지 않습니다.

사전 요청은 사용자 지정 헤더나 특정 형식을 쓸 때 생기므로, 요청에서 그런 요소를 줄이면 사전 요청 자체가 사라지기도 합니다.

4단계 · 응답 헤더 직접 확인

터미널에서 같은 요청을 보내 응답 헤더를 봅니다. 허용 출처와 허용 메서드, 허용 헤더가 모두 필요한 값을 담고 있는지 확인합니다.

인증 정보를 함께 보내는 요청이라면 허용 출처에 별표를 쓸 수 없다는 점도 함께 확인해야 합니다.

5단계 · 중간 경로에서 헤더가 사라지는지 확인

원본 서버에 직접 요청했을 때와 앞단을 거쳤을 때의 응답을 비교합니다. 앞단이 헤더를 지우거나 덮어쓰는 경우가 있습니다.

리다이렉션이 끼어 있으면 최종 응답이 아니라 중간 응답에서 CORS 오류가 나기도 합니다.

6단계 · 설정 적용 후 캐시 확인

사전 요청 결과는 일정 시간 저장됩니다. 서버 설정을 고쳤는데도 같은 메시지가 보인다면 저장된 결과가 남아 있을 수 있습니다.

시크릿 창에서 다시 확인하면 저장된 값의 영향을 받지 않고 결과를 볼 수 있습니다.

내 상황에 맞는 CORS 오류 판단 기준

• Console에 허용 헤더가 없다는 문장이 있다 — 서버에 헤더를 추가해야 합니다.
• 확인용 요청이 먼저 실패한다 — 허용 방식과 허용 헤더 목록을 확인합니다.
• 쿠키를 함께 보낸다 — 인증 허용 설정과 정확한 출처 주소가 필요합니다.
• 중간에 주소가 바뀐다 — 리다이렉션 구간의 헤더 유지를 확인합니다.
• 로컬에서만 발생한다 — 개발 서버의 대리 요청 기능을 사용합니다.

CORS 오류를 확인하는 5단계 체크리스트

1. Console 메시지를 끝까지 읽습니다. 어느 조건이 어긋났는지 문장으로 나옵니다.
2. Network 탭에서 확인용 요청이 있는지 봅니다. 있으면 그 응답부터 확인합니다.
3. 응답 헤더에 허용 출처 항목이 있는지 확인합니다. 없다면 서버 설정 문제입니다.
4. 요청 주소와 현재 페이지 주소를 나란히 비교합니다. 프로토콜, 도메인, 포트를 모두 봅니다.
5. 브라우저 밖에서 같은 요청을 보내 봅니다. 성공하면 서버는 정상이고 헤더만 없는 상태입니다.

CORS 오류에서 흔히 생기는 오해 3가지

첫 번째, 서버가 응답하지 않는다고 보는 시각입니다. 서버는 대부분 정상 응답했습니다. 브라우저가 코드에 전달하지 않은 것뿐입니다.

두 번째, 클라이언트 코드로 우회할 수 있다는 생각입니다. 이 규칙은 브라우저가 강제하므로 요청 방식을 바꿔도 해결되지 않습니다.

세 번째, 모든 출처를 허용하면 끝이라는 판단입니다. 인증이 필요한 요청에서는 이 설정이 오히려 동작하지 않고, 보안상으로도 권장되지 않습니다.

요청 자체가 서버에 닿지 못하고 있다면 CORS 이전 단계의 문제입니다. 연결 자체를 점검하는 순서는 사이트 접속 안 됨 원인 8가지에서 확인할 수 있습니다.

CORS 오류 자주 묻는 질문

주소창에서는 잘 열립니다

문서 이동은 이 규칙의 대상이 아니기 때문입니다. 코드가 응답을 읽으려 할 때만 적용됩니다.

서버 로그에는 성공으로 남습니다

정상입니다. 차단은 브라우저가 응답을 받은 뒤에 수행합니다.

이미지나 스타일시트는 잘 불러와집니다

이런 자원은 읽지 않고 표시만 하므로 규칙이 느슨하게 적용됩니다. 코드로 내용을 읽으려 하면 같은 제한을 받습니다.

외부 API를 쓰는데 설정 권한이 없습니다

서버 쪽에서 대신 요청해 결과만 전달하는 방식으로 우회할 수 있습니다. 브라우저가 아닌 서버끼리의 통신에는 이 규칙이 적용되지 않습니다.

가끔만 발생합니다

여러 대 서버 중 일부에만 헤더 설정이 빠져 있을 수 있습니다. 응답 헤더를 여러 번 확인해 비교해 보십시오.

확인용 요청을 없앨 수 있나요

단순한 형태의 요청으로 바꾸면 발생하지 않습니다. 사용자 정의 헤더를 줄이고 기본 형식을 사용하면 됩니다.

설정을 바꿨는데도 같은 메시지가 나옵니다

사전 요청 결과가 저장되어 있거나 앞단 캐시가 예전 응답을 들고 있는 경우입니다. 시크릿 창에서 확인하고 앞단 캐시도 함께 비워야 합니다.

로그인한 상태에서만 실패합니다

인증 정보를 함께 보내는 요청은 조건이 더 엄격합니다. 허용 출처에 별표 대신 정확한 주소를 적고, 인증 정보 허용 항목을 함께 켜야 합니다.

개발 서버에서만 CORS 오류가 납니다

화면과 서버가 서로 다른 포트에서 동작하기 때문입니다. 개발 서버의 프록시 기능으로 같은 출처처럼 묶으면 설정을 바꾸지 않고도 확인을 이어 갈 수 있습니다.

편집팀 노트 — CORS 오류를 직접 따져보며 정리한 기준

이 글을 정리하면서 편집팀은 같은 요청을 출처와 헤더 조건을 바꿔 가며 보내 결과를 비교했습니다. 가장 자주 시간을 뺏긴 지점은 서버 로그에 성공으로 남아 있는 것을 보고 서버는 정상이라고 판단한 순간이었습니다.

CORS 오류는 서버가 실패한 것이 아니라 브라우저가 응답을 읽지 못하게 막은 결과입니다. 서버 로그에는 200이 남는 것이 정상이므로 로그만 보고 판단하면 원인을 놓치게 됩니다.

또 하나 정리해 둔 기준은 메시지 문구를 그대로 읽는다는 점입니다. 허용 헤더가 없다는 말과 값이 맞지 않는다는 말은 고쳐야 할 곳이 서로 다릅니다.

마지막으로 모든 출처를 허용하는 설정은 피하기를 권합니다. 필요한 주소만 목록으로 관리하면 나중에 어떤 서비스가 이 API를 쓰고 있는지도 함께 남습니다.

핵심 요약

CORS 오류는 서버 장애가 아니라 브라우저의 안전 장치가 동작한 결과입니다. 출처 세 요소를 비교하고, 확인용 요청의 응답을 보고, 허용 헤더가 실제로 붙어 있는지 확인하는 순서로 접근하면 원인이 특정됩니다.

해결은 대부분 서버 설정에서 이루어집니다. 이 글은 정보 제공을 위한 정리이며, 실제 적용은 사용 중인 환경에 맞춰 확인하시기 바랍니다.

함께 보면 좋은 자료와 관련 글

• 개발자 도구 Network 오류 빨간 줄 원인과 확인 순서
• JavaScript 작동 안 함 원인과 Console 확인 순서
• MDN 웹 문서 · 교차 출처 리소스 공유
• MDN 웹 문서 · 허용 출처 헤더

본문에 적은 헤더 이름과 동작은 2026년 8월 기준으로 확인한 내용입니다.

Leek의 블로그 홈으로

다른 속도 최적화와 문제 해결 가이드도 홈에서 모아 보실 수 있습니다.