톰캣FileCountLimitExceededException 문제 해결

문제 상황: 10장 이상의 이미지를 올릴 때 발생한 오류

호텔 등록 기능을 구현하면서 여러 장의 이미지를 업로드할 수 있도록 만들었습니다. 그런데 이미지를 10장 이상 업로드하는 순간, 서버에서 FileCountLimitExceededException이라는 예상치 못한 오류를 만났습니다. 이 오류는 톰캣 서버의 기본 설정이 한 번에 받을 수 있는 파일의 개수를 초과했을 때 발생하는 전형적인 문제입니다.

첫 번째 시도: application.yml은 왜 실패했을까?

대부분의 Spring Boot 설정은 application.yml 파일을 통해 쉽게 변경할 수 있습니다. 처음에는 이 오류도 파일 크기 문제일 것이라고 생각하고, 아래와 같이 관련 설정을 변경해 보았습니다.

spring:
  servlet:
    multipart:
      max-file-size: 50MB # 개별 파일 크기
      max-request-size: 100MB # 전체 요청 크기

하지만 이 설정들은 개별 파일 크기(max-file-size)나 전체 요청 본문 크기(max-request-size)를 제어하는 용도일 뿐, 한 번에 업로드할 수 있는 파일의 개수(maxParts)를 직접적으로 제한하는 설정이 아니었습니다. 이 때문에 아무리 값을 크게 설정해도 FileCountLimitExceededException 오류는 계속해서 발생했습니다.

해결 방안: 톰캣 커스터마이징으로 직접 제어하기

application.yml에 직접적인 설정 옵션이 없는 경우, Spring Boot의 유연성을 활용하여 내장 톰캣 서버의 설정을 직접 커스터마이징하는 방법으로 문제를 해결할 수 있습니다.

TomcatServletWebServerFactory를 사용해 톰캣 커넥터의 세부 속성을 직접 수정하는 빈(Bean)을 등록했습니다. 이 과정에서 setMaxPartCount() 메서드를 호출하여 파일 개수 제한을 늘려주는 것이 핵심입니다.

package com.beyond.HanSoom.common.config;

import org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory;
import org.springframework.boot.web.server.WebServerFactoryCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class TomcatConfig {

    @Bean
    public WebServerFactoryCustomizer<TomcatServletWebServerFactory> multipartConfigCustomizer() {
        return factory -> {
            factory.addConnectorCustomizers(connector -> {
                // 톰캣의 최대 파일 개수 제한을 20개로 설정
                connector.setMaxPartCount(30);
            });
        };
    }
}

위와 같이 TomcatConfig 클래스를 만들어 setMaxParts 값을 기본값(10)보다 큰 값으로 설정함으로써, 파일 개수 제한 문제를 해결하고 10장 이상의 이미지를 정상적으로 업로드할 수 있게 되었습니다.

결론적으로, FileCountLimitExceededException은 파일의 크기가 아닌 개수와 관련된 오류이며, application.yml에 없는 톰캣의 세부 설정은 TomcatServletWebServerFactory를 통해 직접 제어해야 함을 알 수 있었습니다.