git push 'RPC failed; HTTP 413' 해결: 원인 판별부터 대용량 파일 정리까지

결론부터: 이 에러는 "서버(또는 앞단 프록시)가 요청 본문이 너무 크다고 거절했다"는 뜻

error: RPC failed; HTTP 413 curl 22 The requested URL returned error: 413
send-pack: unexpected disconnect while reading sideband packet
fatal: the remote end hung up unexpectedly
Everything up-to-date

413은 HTTP 상태 코드 "Content Too Large"(RFC 9110 §15.5.14)이며, git 클라이언트가 아니라 원격 서버나 그 앞의 리버스 프록시가 돌려준 응답입니다. 마지막 줄 Everything up-to-date는 아무것도 올라가지 않았다는 뜻이지 성공이 아닙니다. 해결은 둘 중 하나입니다: (1) 서버 쪽 업로드 한도를 올리거나, (2) 푸시에 들어간 큰 파일을 빼서 푸시 크기를 줄인다.

범위: HTTPS 리모트에서 git push가 413으로 실패하는 경우. 인증 에러는 SSH Permission denied (publickey) 진단, non-fast-forward 거부는 git push 거부 non-fast-forward 해결법을 보세요.

원인

• 프록시/웹서버의 요청 본문 한도. 예를 들어 nginx의 client_max_body_size는 기본값이 1m이고, 이를 넘는 요청에는 413을 반환합니다(nginx 공식 문서). 자체 호스팅 GitLab·Gitea 앞에 nginx를 둔 구성에서 흔합니다.
• 푸시에 큰 파일이 섞임. 빌드 산출물, 데이터셋, 영상 등을 실수로 커밋하면 push 요청(pack)이 한도를 넘습니다.
• http.postBuffer는 원인도 해결책도 아닌 경우가 대부분. git 공식 문서는 이 값을 올리는 것이 "대부분의 push 문제에 효과적인 해결책이 아니며" chunked 전송을 지원하지 않는 서버·프록시용이라고 설명합니다(git-config: http.postBuffer). 아래 실험에서도 50 MiB로 올려도 413은 그대로였습니다.
• GitHub에 푸시하는 경우: GitHub는 100 MiB를 넘는 파일을 차단하고, 50 MiB를 넘으면 경고합니다(GitHub Docs). 이때는 413이 아니라 GitHub의 거절 메시지가 나오므로 아래 "큰 파일 빼기" 절차를 그대로 쓰면 됩니다.

확인 명령

1) 413을 누가 돌려주는지 확인 — GIT_TRACE_CURL은 HTTP 요청/응답 헤더를 출력합니다(git 문서).

GIT_TRACE_CURL=1 GIT_TRACE_CURL_NO_DATA=1 git push origin main 2>&1 \
  | grep -E "Send header: POST|Recv header: HTTP/|Recv header: Server"

=> Send header: POST /repo.git/git-receive-pack HTTP/1.1
<= Recv header: HTTP/1.1 413 Request Entity Too Large

git-receive-pack POST에 413이 오고, Server: 헤더(예: nginx)로 어느 계층이 막았는지 짐작할 수 있습니다.

2) 이번 푸시에 무엇이 들어가는지, 가장 큰 객체가 무엇인지 — git cat-file --batch-check로 크기를 봅니다.

git log --oneline @{u}..HEAD
git rev-list --objects @{u}..HEAD \
  | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \
  | sort -k3 -n -r | head -5

blob f893be8925fb500da6eff6f019f7a4e09d002b18 5000000 big.bin
commit 2b56827b2eee814c4e8070d5cfdce446f703e082 203

5,000,000바이트짜리 big.bin이 원인이라는 것이 바로 보입니다.

해결 절차

A. 서버 관리자라면: 업로드 한도를 올린다

server {
    # ...
    location /repo.git/ {
        client_max_body_size 50m;   # value is an example; size it to your largest push
        # ... existing proxy_pass / fastcgi settings
    }
}

sudo nginx -t && sudo nginx -s reload

client_max_body_size는 http, server, location 컨텍스트에 둘 수 있으므로(nginx 문서) git 경로에만 올리는 것을 권장합니다. nginx 자체 413 대응 전반은 nginx 413 Request Entity Too Large 진단 가이드를 참고하세요.

B. 큰 파일이 아직 푸시 안 된 마지막 커밋에만 있다면: 커밋에서 뺀다 (GitHub Docs가 안내하는 방식과 동일, 출처)

git rm --cached big.bin
echo "big.bin" >> .gitignore
git add .gitignore
git commit --amend -CHEAD
git push origin main

C. 큰 파일을 계속 버전 관리해야 한다면: Git LFS로 옮긴다 — git lfs migrate import는 지정한 ref의 이력을 다시 써서 파일을 LFS 포인터로 바꿉니다(git-lfs-migrate). 이미 푸시된 ref는 --exclude-ref로 제외해야 공유 이력이 바뀌지 않습니다. 서버가 LFS를 지원해야 하며, GitHub의 LFS 파일 크기 한도는 요금제별로 다릅니다(GitHub Docs: Git LFS).

git lfs install --local
git lfs migrate import --include="*.dat" \
  --include-ref=refs/heads/main --exclude-ref=refs/remotes/origin/main
cat .gitattributes          # *.dat filter=lfs diff=lfs merge=lfs -text
git show HEAD:big2.dat | head -3   # version https://git-lfs.github.com/spec/v1 ...

D. 큰 파일이 더 이전 커밋에 묻혀 있다면: git filter-repo로 이력에서 제거 — GitHub Docs도 이 도구를 권장합니다(출처, git-filter-repo 문서). 이력을 다시 쓰므로 새 클론에서 작업하고, 협업자에게 미리 알리세요.

git clone <repo-url> repo-clean && cd repo-clean
git filter-repo --path old.iso --invert-paths
git remote add origin <repo-url>   # filter-repo removes the origin remote

비밀 키를 푸시한 경우라면 이력 정리보다 키 폐기가 먼저입니다: .env·API 키 git에 실수로 push 했을 때.

검증 환경과 결과

로컬 샌드박스(Debian, git 2.47.3, nginx 1.26.3 + git-http-backend, git-lfs 3.6.1, git-filter-repo)에서 client_max_body_size 1m인 HTTPS 리모트에 5 MB 파일을 푸시해 위 에러 원문과 trace 출력을 그대로 재현했습니다. -c http.postBuffer=52428800로는 여전히 413, 절차 B 적용 후 푸시 성공, 절차 C 후 파일이 LFS 포인터로 바뀐 것, 절차 D 후 해당 파일이 이력에서 사라지고 origin 리모트가 제거된 것을 확인했습니다. 절차 A는 한도를 50m로 올린 뒤 같은 크기의 POST가 더 이상 413을 받지 않는 것까지 확인했습니다.

기준일: 2026-10-22. 버전별 동작은 사용 중인 git·nginx 버전 문서로 다시 확인하세요.

git push (client_max_body_size 1m, 5MB file) -> HTTP 413
git -c http.postBuffer=52428800 push -> still 413
GIT_TRACE_CURL=1 git push
git rev-list --objects @{u}..HEAD | git cat-file --batch-check
git rm --cached + git commit --amend -CHEAD + git push -> success
git lfs migrate import --include=*.dat --exclude-ref=refs/remotes/origin/main
git filter-repo --path old.iso --invert-paths
nginx client_max_body_size 50m -> POST no longer 413