파일 업로드가 안 될 때 확인하는 것들

파일 업로드가 안 될 때는 원인이 프런트엔드일 수도, 요청 형식일 수도, 서버 제한일 수도 있다. 한 화면만 봐서는 어디서 막혔는지 모른다. 그래서 나는 요청을 끊어서 확인한다.

요청 형식부터 본다

업로드는 보통 multipart/form-data로 보내야 한다. 그런데 Content-Type을 직접 application/json으로 박아두거나, fetch에서 FormData를 쓰면서 헤더를 수동으로 지정해 경계 문자열(boundary)을 깨먹는 실수가 흔하다.

const form = new FormData();
form.append("file", file);
// Content-Type을 직접 지정하지 않는다. 브라우저가 boundary까지 붙여준다.
fetch("/api/upload", { method: "POST", body: form });

curl로 서버만 따로 때려본다

프런트를 빼고 서버가 받는지 직접 확인하면 범위가 절반으로 준다.

curl -i -X POST https://example.com/api/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./test.png"

-i로 응답 헤더와 상태 코드를 본다. 401이면 인증, 413이면 용량 제한, 415면 타입 문제다.

용량 제한을 확인한다

413(Payload Too Large)이 나오면 앱 코드가 아니라 그 앞단을 본다. nginx면 client_max_body_size, 프레임워크면 바디 파서의 limit 설정이다. 인증 상태와 용량 제한, 이 둘만 먼저 걸러도 대부분의 업로드 실패는 원인이 좁혀졌다.