Java - ClassNotFoundException 발생 원인 및 해결 방법

java.lang.ClassNotFoundException 에러는 프로그램 실행 중 객체를 생성할 때 클래스를 찾지 못하면 발생하는 Exception입니다.

1. 문제 원인

클래스를 못찾는 이유는 다양할 수 있는데, 첫번째로 개발하고 있는 IDE의 컴파일 문제로, 내가 추가한 클래스가 JAR에 추가되지 않고 프로그램이 실행되었을 수 있습니다. 또는, 사용하고 있는 라이브러리에서 다른 라이브러리를 사용하고 있는데, 호환성 문제로(클래스가 정의되지 않은 낮은 버전의 라이브러리를 사용) 클래스를 찾지 못할 수 있습니다.

2. 해결 방법 1

기본적으로 자바 프로그램이 실행될 때, 설정된 classpath 경로에서 클래스를 찾습니다. 내 프로그램이 여러 외부 라이브러리를 사용한다면, 이 라이브러리에 대한 위치가 classpath에 함께 추가됩니다. 클래스를 못찾았다는 것은 이 classpath에 정의된 경로의 JAR 파일들에서 클래스를 못찾았다는 의미가 됩니다. 간혹, IDE에서 프로젝트를 생성하고, 그 프로젝트에서 여러 모듈로 분리하여 개발할 때 일부 모듈이 컴파일되지 않는 경우가 있습니다. 이럴 때 Main 클래스는 하위 모듈에 있는 클래스의 존재를 알고 있어서 컴파일이 되었는데, 신규 클래스가 추가된 하위 모듈은 컴파일되지 않을 수 있습니다. 프로그램이 실행되면 Main 클래스는 예전에 빌드된 하위 모듈의 JAR를 사용할 수 있는데 이 때 ClassNotFoundException가 발생할 수 있습니다.

해결 방법은 빌드 산출물을 모두 클리어 및 초기화하여 다시 빌드하는 것입니다.

3. 해결 방법 2

내가 사용하는 외부 라이브러리의 호환성 문제로 발생하는 경우입니다.

예를 들어, 메인 모듈에서 UserLibrary.jar 라는 외부 라이브러리를 사용하고 있습니다. UserLibrary.jar는 math_version_2.jar라는 외부 라이브러리를 사용하여 컴파일되었습니다. math_version_2.jar는 math_version1.jar에서 ConvertFloatToInt라는 신규 클래스가 추가되었습니다.

이럴 때, 내 프로젝트가 UserLibrary.jar와 math_version1.jar를 사용한다면, 호환성 문제로 ConvertFloatToInt 클래스를 찾지 못하여 ClassNotFoundException이 발생할 수 있습니다.

해결 방법은 라이브러리의 호환성 문제가 발생하지 않도록 올바른 버전을 추가하는 것입니다. 보통 Maven이나 Gradle에서 어떤 라이브러리를 로딩할 때, 그 라이브러리가 사용하는 라이브러리를 모두 추가해주는데요, 여러 라이브러리가 공통적으로 사용하는 라이브러리가 있을 때 버전 문제가 발생할 수 있습니다. 또는 IDE 문제로, 의존성 라이브러리를 제대로 로딩시켜주지 않을 때가 있습니다. 이런건 툴 문제니, 프로젝트 빌드 산출물을 클리어하고 프로그램을 재시작하면 해결될 수 있습니다.

내 잘못이 아니고, 툴이 잘못해서 발생되는 문제라면 오랜 시간 삽질할 수 있습니다. 잘되던게 갑자기 안된다 싶으면 빌드 산출물을 클리어하고 프로그램 재시작해보시는 것이 좋을 것 같습니다. 그래도 문제가 해결안되면 그 클래스를 사용하는 라이브러리를 살펴보시는 것이 좋을 것 같습니다.

References

• stackoverflow
• oracle