VS Code에서 org.springframework.messaging 인식 안 됨 해결

 

프로젝트를 진행하면서 WebSocket을 추가하고, 실시간 협업 기능을 위해 보안 로직(STOMP 인증, Origin 검증 등)을 강화하였습니다.

이때 Spring Messaging 기능을 사용하기 위해 spring-boot-starter-websocket 의존성을 추가하였습니다.

그런데 프로젝트에서 계속해서 SimpMessagingTemplate 클래스를 인식하지 못하는 문제가 발생했습니다.
의존성은 분명히 추가되어 있었고, Gradle refresh, IDE 재시작 등 모든 기본적인 조치를 취했음에도 에러가 사라지지 않았습니다.

---

증상

 

• import org.springframework.messaging.SimpMessagingTemplate; 에서
  “cannot be resolved” 에러 발생
• SimpMessagingTemplate 심볼을 찾지 못하며 빨간 밑줄이 표시됨

 

 

The import org.springframework.messaging cannot be resolved (Java 268435846)

---

환경

• IDE: VS Code (Java Extension Pack)
• 빌드: Gradle (Wrapper)
• 스프링: Spring Boot (WebSocket/STOMP)
• 모듈: spring-messaging (또는 spring-boot-starter-websocket에 포함)

---

코드

WebSocket 이벤트 퍼블리셔에서 아래와 같이 SimpMessagingTemplate를 주입해 사용했습니다.

import org.springframework.messaging.simp.SimpMessagingTemplate;

@Component
public class CollaborationEventPublisher {
    private final SimpMessagingTemplate messagingTemplate;

    public CollaborationEventPublisher(SimpMessagingTemplate messagingTemplate) {
        this.messagingTemplate = messagingTemplate;
    }

    public void publishTaskEvent(TaskEventMessage message) {
        messagingTemplate.convertAndSend("/topic/tasks", message);
    }
}

 

하지만 VS Code에서는 위 코드의 import 라인에 계속 빨간 밑줄이 표시되었고, IDE 상에서는 컴파일 에러처럼 인식되었습니다.
빌드(./gradlew check)는 정상적으로 통과했기 때문에, IDE만 인식하지 못하는 현상이었습니다. 

---

시도한 방법

1. Gradle 프로젝트 리프레시
2. ./gradlew --refresh-dependencies
3. IDE 재시작 (창 리로드 포함)
4. ./gradlew clean build

이 모든 방법을 시도해도 에러는 그대로 남아 있었습니다.

---

원인 추정

문제를 조사해본 결과, 이는 VS Code의 Java Language Server(JDT LS) 가
Gradle 의존성 정보를 오래된 캐시로 보관하고 있어서 생기는 현상이었습니다.

다시 말해,

• Gradle의 소스셋/의존성 인덱스가 꼬였거나
• 멀티모듈 구조 변경 이후 Symbol 인식이 잘못된 상태로 남은 경우입니다.

이런 경우 빌드는 멀쩡히 통과하지만 IDE만 오탐을 일으키는 현상이 발생합니다.

---

 

해결 방법

1) Java Language Server 캐시 초기화 (가장 효과적)

1. Command Palette 열기 (Ctrl + Shift + P)
2. Java: Clean Java Language Server Workspace 실행
3. VS Code가 “창 리로드”를 제안하면 수락
4. 인덱싱이 완료될 때까지 잠시 대기

이 단계를 수행한 직후, SimpMessagingTemplate 인식 에러가 바로 사라졌습니다.

---

2) 보조 점검

 - Gradle 클린 빌드

./gradlew clean build

 

 - Gradle 캐시 초기화

 

 

 그래도 안 풀릴 경우, 전체 캐시를 삭제하고 다시 의존성을 받습니다. (주의: 전체 캐시 삭제는 시간이 오래 걸릴 수 있습니다.)

rm -rf ~/.gradle/caches
./gradlew --refresh-dependencies

 

 

 - Java 익스텐션 로그 확인

Command Palette → Java: Open Java Language Server Log
에서 인덱싱 오류 로그를 확인할 수 있습니다.

---

혹시 모를 의존성 체크리스트

저는 캐시 문제였지만, 아래 사항도 함께 점검하면 좋습니다.

 

1. 의존성

spring-boot-starter-websocket을 사용하면 spring-messaging이 자동으로 포함됩니다.
만약 직접 추가한다면 다음과 같이 명시할 수 있습니다:

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-websocket'
    // 또는
    implementation 'org.springframework:spring-messaging'
}

 

 

2. JDK 버전

 

• build.gradle의 sourceCompatibility와 실제 실행 중인 JDK 버전이 일치하는지 확인합니다.
• VS Code 오른쪽 하단에 표시되는 JDK가 프로젝트 설정과 같은지 확인합니다.

3.. 멀티 모듈 구조

 

• 해당 모듈이 settings.gradle에 포함되어 있는지
• 모듈 내 build.gradle에 java 또는 java-library 플러그인이 선언되어 있는지 확인합니다.

 

 

---

재발 방지 팁

• 의존성이나 모듈 구조를 크게 바꾼 후에는
  1. ./gradlew clean
  2. Java: Clean Java Language Server Workspace
     순서로 진행하면 문제를 예방할 수 있습니다.
• VS Code 설정에서 “Auto build” 옵션을 켜두면 인덱싱이 자동으로 재시도되어 문제를 줄일 수 있습니다.
• 캐시가 자주 꼬인다면, Workspace 전용 JDK와 프로젝트 JDK를 명확히 분리해두는 것이 좋습니다.

---

마무리

이번 이슈는 코드나 빌드 문제가 아닌 IDE 인덱스 캐시 문제였습니다.
Gradle 리프레시나 재시작으로 해결되지 않는다면,
Java: Clean Java Language Server Workspace 명령이 가장 빠르고 확실한 해결책입니다.