IntelliJ Cannot resolve symbol 빨간 글씨 해결: Project SDK·Gradle 재동기화·캐시 점검 (2026년 8월 28일 기준)

 

IntelliJ IDEA에서 분명히 존재하는 클래스나 메서드인데도 코드 곳곳이 빨간 줄로 표시되고 Cannot resolve symbol 오류가 뜨는 경우가 있다. 실제 컴파일 오류가 아니라 IDE가 프로젝트 구성을 제대로 인식하지 못해 생기는 인덱싱·동기화 문제일 수 있다. 코드를 무작정 고치기 전에 Project SDK 설정과 Gradle 동기화 상태부터 순서대로 점검하면 원인을 좁히기 쉽다. 이 글은 2026년 8월 28일 JetBrains 공식 문서를 바탕으로 점검 순서를 정리한다.

빠른 결론
1) File > Project Structure에서 Project SDK와 Module SDK를 먼저 확인한다.
2) build.gradle(.kts) 수정 후 Gradle을 재동기화하고 Rebuild Project를 실행한다.
3) 그래도 남으면 마지막 단계로 Invalidate Caches를 신중히 사용한다.

점검 체크리스트

항목	확인 위치	비고
Project SDK	File > Project Structure > Project	프로젝트 전체 기본 JDK
Module SDK	Project Structure > Modules > Dependencies	모듈별로 달라질 수 있음
Gradle 동기화	build.gradle(.kts) 수정 후 reload	도구창 아이콘 또는 단축키
External Libraries	프로젝트 트리 하단	의존성 다운로드 여부 확인
캐시 상태	File > Invalidate Caches	마지막 수단, 옵션 주의

단계별 점검 순서

1. 오류 범위를 구분한다. java.lang.String처럼 JDK 기본 클래스까지 빨간색이면 SDK 문제를 먼저 의심한다. 특정 외부 라이브러리만 보이지 않으면 Gradle 의존성과 동기화를 우선 확인한다.
2. Project SDK를 확인한다. File > Project Structure > Project Settings > Project에서 Project SDK가 비어 있거나 프로젝트 요구 JDK와 다른지 본다.
3. Module SDK를 확인한다. Project Structure > Modules > Dependencies에서 Module SDK가 Project SDK를 상속하는지, 특정 모듈만 다른 SDK를 쓰는지 점검한다.
4. build.gradle(.kts) 의존성을 확인한다. 빨간 줄이 뜨는 심볼이 속한 라이브러리가 dependencies 블록에 선언되어 있는지, 이름·버전·scope 표기에 오타가 없는지 본다.
5. Gradle을 재동기화한다. Gradle 도구창의 Reload All Gradle Projects 아이콘을 누른다. 공식 가이드의 단축키는 Windows·Linux Ctrl+Shift+O, macOS Cmd+Shift+I다.
6. External Libraries를 확인한다. 문제 라이브러리가 목록에 실제로 나타나는지 본다. 없으면 동기화가 끝나지 않았거나 저장소 접근·버전 해석 오류가 남은 것이다.
7. 프로젝트를 다시 빌드한다. Build > Rebuild Project를 실행해 동기화된 설정으로 전체 빌드를 다시 확인한다.

주의사항

Project SDK나 Module SDK를 이유 없이 최신 버전으로 바꾸면 프로젝트가 요구하는 언어 레벨과 맞지 않아 새로운 컴파일 오류가 생길 수 있다. build.gradle(.kts)의 toolchain·sourceCompatibility 설정이나 프로젝트 문서를 먼저 확인한 뒤 SDK 버전을 조정한다.

해결되지 않을 때 추가 점검

• Gradle 버전과 Gradle JVM이 프로젝트 요구사항과 맞는지 다시 확인한다. Gradle 버전 변경 글과 Gradle JVM 오류 해결 글을 참고한다.
• 인덱싱이 중간에 멈추거나 IDE가 지나치게 느리면 IDE 힙과 빌드 힙 구분 글에서 메모리 설정을 확인한다.
• SDK·Gradle 문제를 정리한 뒤에도 실행 오류가 남으면 심볼 인식 문제와 구분한다. 포트 충돌은 Spring Boot 8080 포트 오류 글에서 별도로 다룬다.
• 마지막으로 File > Invalidate Caches > Invalidate and Restart를 사용한다. 추가 선택 항목은 Local History, VCS Log 캐시 등 별도 데이터를 지울 수 있으므로 필요한 항목만 고른다.

FAQ

Q1. Cannot resolve symbol이 뜨는데 실제 빌드는 성공합니다. 왜 그런가요?

IDE 인덱스·프로젝트 모델이 실제 Gradle 빌드 결과와 어긋나 있을 수 있다. Gradle 재동기화와 Rebuild Project를 먼저 실행하고, 빨간 줄이 남으면 캐시 무효화를 고려한다.

Q2. Project SDK와 Module SDK를 둘 다 확인해야 하나요?

Project SDK는 프로젝트 전역 기본값이고 Module SDK는 개별 모듈이 상속하거나 별도로 지정할 수 있는 값이다. 설정이 어긋나면 특정 모듈에서만 심볼 오류가 날 수 있다.

Q3. Invalidate Caches를 가장 먼저 해도 되나요?

캐시 무효화는 인덱스를 처음부터 다시 만들며 재인덱싱 시간이 걸린다. 선택 항목에 따라 Local History 등이 삭제될 수 있으므로 SDK와 Gradle 동기화 점검 뒤 마지막 단계로 사용하는 편이 안전하다.

공식 출처

• JetBrains 공식 도움말 - SDK 설정
• JetBrains 공식 가이드 - Gradle Syncing and reloading
• JetBrains 공식 도움말 - Invalidate Caches

---