에러의 핵심 의미
이 에러 메시지는 이름 그대로입니다.
“클라이언트(브라우저)가 서버로 보낸 요청의 헤더(Header) 또는 쿠키(Cookie)의 크기가 너무 커서, 서버가 처리를 거부했습니다.”
대부분의 웹 서버(Nginx, Apache 등)는 비정상적으로 큰 헤더를 보내는 공격(DDoS 등)을 방지하기 위해 헤더 크기에 대한 기본 제한을 가지고 있습니다. 일반적인 요청에서는 이 제한을 넘을 일이 거의 없지만, 특정 상황에서 문제가 발생할 수 있습니다.
주요 발생 원인
- 누적된 쿠키 (가장 흔한 원인):
- 웹사이트를 이용하면서 로그인 정보, 사용자 설정, 추적 정보 등 수많은 쿠키가 브라우저에 쌓이게 됩니다.
- 특히 여러 하위 도메인(
a.example.com,b.example.com)이 모두 루트 도메인(.example.com)에 쿠키를 설정하는 경우, 쿠키의 총 크기가 매우 빠르게 커질 수 있습니다. - 브라우저는 해당 도메인에 요청을 보낼 때마다 이 모든 쿠키를 헤더에 담아 보내므로, 크기 제한을 초과하게 됩니다.
- 큰 인증 토큰 (JWT 등):
Authorization헤더에 담기는 JWT(JSON Web Token)에 사용자의 역할, 권한 등 너무 많은 정보를 담으면 토큰의 크기가 커져서 문제를 일으킬 수 있습니다.
- 기타 큰 헤더 정보:
Referer헤더에 매우 긴 URL이 포함되거나, 개발 중에 비정상적으로 큰 커스텀 헤더를 사용하는 경우에도 발생할 수 있습니다.
해결 방법
해결 방법은 크게 두 가지 접근법이 있습니다. 서버의 허용치를 늘리는 임시방편적인 방법과, 요청 헤더 크기 자체를 줄이는 근본적인 방법입니다.
해결 방법 1: 서버의 헤더 크기 제한 늘리기 (서버 관리자/개발자용)
사용 중인 웹 서버의 설정 파일을 수정하여 허용 가능한 헤더의 최대 크기를 늘려주는 방법입니다.
✅ Nginx 사용 시
Nginx에서는 large_client_header_buffers 지시어를 사용합니다.
- Nginx 설정 파일을 엽니다. (보통
/etc/nginx/nginx.conf또는/etc/nginx/sites-available/default) http또는server블록 내에 아래 내용을 추가하거나 수정합니다.large_client_header_buffers number size;number: 버퍼의 개수size: 각 버퍼의 크기. (예: 8k, 16k, 32k)- 기본값은 보통
4 8k(8KB짜리 버퍼 4개, 총 32KB)입니다. 이를 2~4배 정도 늘려줍니다.1234567891011121314151617<code class="whitespace-pre-wrap break-words"><span class="line"><span>http {</span></span><span class="line"><span> # ... (다른 설정들)</span></span><span class="line"><span></span></span><span class="line"><span> # 기본값보다 2배 늘린 예시 (총 64KB)</span></span><span class="line"><span> large_client_header_buffers 4 16k;</span></span><span class="line"><span></span></span><span class="line"><span> # ...</span></span><span class="line"><span>}</span></span><span class="line"><span></span></span><span class="line"><span># 또는 특정 서버에만 적용할 경우</span></span><span class="line"><span>server {</span></span><span class="line"><span> # ...</span></span><span class="line"><span></span></span><span class="line"><span> large_client_header_buffers 4 16k;</span></span><span class="line"><span></span></span><span class="line"><span> # ...</span></span><span class="line"><span>}</span></span><span style="font-family: Consolas, Monaco, monospace; background-color: #ffffff; color: #333333; font-size: 16px;"></span></code>
- 설정 파일의 문법을 확인하고 Nginx를 재시작합니다.
12<code class="whitespace-pre-wrap break-words"><span class="line"><span>sudo</span><span> nginx</span><span> -t</span></span><span class="line"><span>sudo</span><span> systemctl</span><span> restart</span><span> nginx</span></span></code>
✅ Apache 사용 시
Apache에서는 LimitRequestFieldSize 지시어를 사용합니다.
- Apache 설정 파일을 엽니다. (보통
/etc/httpd/conf/httpd.conf또는/etc/apache2/apache2.conf) LimitRequestFieldSize값을 늘려줍니다. 기본값은8190(약 8KB)입니다.12<code class="whitespace-pre-wrap break-words"><span class="line"><span># 16KB로 늘리는 예시</span></span><span class="line"><span>LimitRequestFieldSize 16380</span></span></code>- Apache를 재시작합니다.
12345<code class="whitespace-pre-wrap break-words"><span class="line"><span># CentOS/RHEL</span></span><span class="line"><span>sudo</span><span> systemctl</span><span> restart</span><span> httpd</span></span><span class="line"></span><span class="line"><span># Debian/Ubuntu</span></span><span class="line"><span>sudo</span><span> systemctl</span><span> restart</span><span> apache2</span></span></code>
✅ Spring Boot (내장 Tomcat/Jetty) 사용 시
application.properties 또는 application.yml 파일에 다음 속성을 추가합니다.
|
1 2 |
<code class="whitespace-pre-wrap break-words"><span class="line"><span># application.properties</span></span> <span class="line"><span>server.max-http-header-size=16384 # 16KB로 설정 (단위: bytes)</span></span><span style="font-family: Consolas, Monaco, monospace; background-color: #ffffff; color: #333333; font-size: 16px;"></span></code> |
|
1 2 3 |
<code class="whitespace-pre-wrap break-words"><span class="line"><span># application.yml</span></span> <span class="line"><span>server</span><span>:</span></span> <span class="line"><span> max-http-header-size</span><span>: </span><span>16KB</span><span> # 또는 16384</span></span></code> |
해결 방법 2: 요청 헤더 크기 줄이기 (근본적인 해결책)
서버 설정을 바꾸는 것은 임시방편일 수 있습니다. 근본적으로는 클라이언트가 보내는 헤더의 크기를 줄여야 합니다.
- 불필요한 쿠키 삭제 (개발자/기획자):
- 웹 애플리케이션에서 더 이상 사용하지 않거나 만료된 쿠키를 정리하는 로직을 추가합니다.
- 모든 정보를 쿠키에 저장하려 하지 말고, 정말 필요한 최소한의 식별자만 저장합니다.
- 단순히 클라이언트 측에서만 필요한 정보(예: UI 상태)는 쿠키 대신 **
localStorage또는sessionStorage**에 저장하는 것을 고려하세요. 이들은 서버로 매번 전송되지 않습니다.
- JWT 등 토큰 사이즈 최적화 (개발자):
- 인증 토큰에 꼭 필요한 정보(예: 사용자 ID, 만료 시간)만 담고, 부가적인 사용자 정보는 별도의 API 호출을 통해 가져오도록 설계합니다.
- 브라우저 쿠키 삭제 (일반 사용자):
- 만약 특정 웹사이트에 접속하는 일반 사용자로서 이 에러를 겪는다면, 가장 간단한 해결책은 해당 사이트의 쿠키와 캐시를 삭제하는 것입니다.
- Chrome 기준:
설정 > 개인정보 보호 및 보안 > 쿠키 및 기타 사이트 데이터 > 모든 쿠키 및 사이트 데이터 보기에서 해당 사이트의 쿠키를 검색하여 삭제합니다.
요약 및 해결 순서
- [가장 먼저] 일반 사용자라면 브라우저의 해당 사이트 쿠키를 삭제해 보세요. 대부분 해결됩니다.
- [개발자] 브라우저 개발자 도구(F12)의 ‘Network’ 탭에서 실제 요청 헤더의 크기와 내용을 확인하여 어떤 쿠키나 헤더가 문제인지 분석합니다.
- [근본적 해결] 분석 결과를 바탕으로 불필요한 쿠키를 제거하고,
localStorage등을 활용하여 헤더 크기를 줄이는 방향으로 코드를 리팩토링합니다. - [임시적 해결] 당장 코드 수정이 어렵다면, 위에서 안내한 방법대로 웹 서버(Nginx, Apache 등)의 헤더 크기 제한을 늘려 급한 불을 끕니다.
가장 좋은 방법은 3번과 4번을 병행하는 것입니다. 먼저 서버 제한을 늘려 서비스를 정상화시킨 후, 근본적인 원인을 해결하여 장기적으로 문제가 재발하지 않도록 하는 것이 좋습니다.