서버 운영

Gradle 빌드가 서버에서만 실패할 때

Java 애플리케이션이 로컬에서는 빌드되지만 서버 환경에서만 Gradle 빌드가 실패하는 문제를 다루는 방법입니다.

2026년 6월 24일·1분 읽기

Gradle 빌드 문제는 보통 로컬과 서버의 환경 차이에서 비롯된다. 문제를 크게 잡으면 모든 파일이 의심스러워져서 손대기 어려워진다.

핵심은 운영 환경 전체 흐름을 따라가면서 하나씩 확인하는 것이다. 재현 조건, 로그, 응답처럼 눈으로 확인할 수 있는 값들을 먼저 모아야 한다.

서버의 리소스 상태 확인

빌드 실패는 대부분 리소스 부족에서 비롯된다. 메모리, 디스크 용량, CPU 모두 확인해야 한다.

sudo ss -lntp
df -h
sudo journalctl -n 80

ss 명령어로 포트와 프로세스를 본다. df로 디스크 용량을 확인한다. journalctl로 시스템 로그에서 에러를 찾는다.

같은 빌드 명령을 실행해도, 서버의 부하가 높은 시간대에는 실패할 수 있다. 다른 서비스가 돌아가고 있진 않은지, 크론 작업이 실행 중인 건 아닌지 확인한다.

top

현재 프로세스의 CPU와 메모리 사용량을 본다. 예상보다 높으면 다른 서비스가 경합하고 있다는 뜻이다.

Java 메모리 설정이 로컬과 서버에서 다르면, 같은 코드도 다르게 동작한다. 힙 메모리 크기, 가비지 컬렉션 설정 등이 달라질 수 있다.

Gradle 빌드 시 환경 변수나 gradle.properties 파일을 확인한다. JAVA_OPTS나 ORG_GRADLE_PROJECT_* 변수들이 제대로 설정되었는지 본다.

빌드 로그가 길 때는 처음부터 끝까지 다 읽을 필요는 없다. "ERROR", "Exception", "failed"라는 단어를 찾아서 그 주변을 자세히 본다.

특히 컴파일 에러인지, 테스트 실패인지, 아니면 리소스 부족인지 구분해야 한다. 각 경우마다 해결 방법이 다르다.

빌드 디렉토리나 캐시 디렉토리에 쓰기 권한이 없으면 빌드가 실패한다. 특히 /tmp나 ~/.gradle 디렉토리의 권한을 확인한다.

ls -la ~/.gradle

체크리스트:

한 번에 여러 설정을 바꾸지 않는 것만으로도 원인 추적이 쉬워진다. 관련 기록을 짧게라도 남겨두면 다음 확인이 훨씬 빨라진다.