[Java, Eclipse] 원격 디버깅(Remote debugging) | Invalid thread access

 

 

Java는 기본적으로 JDWP (Java Debug Wire Protocol) 을 통해
외부에서 JVM에 디버거를 붙일 수 있는 기능을 제공합니다.

즉,

• 서버 JVM이 "디버거를 받아들일 준비"(server=y)를 하고,
• Eclipse가 "디버거 클라이언트"로서 접속하는 구조입니다.

 

아래 글은 서버에서 실행 중인 Java 프로그램을 Eclipse로 원격 디버깅하는 방법을 정리했습니다.
이 방법을 사용하면 실제 서버에서 돌아가는 프로그램의 상태를 Eclipse에서 로컬 디버깅하듯 브레이크포인트로 멈추고 변수 값을 확인할 수 있습니다.

 

 

---

⚙️ 1. 서버 측 설정 (배치파일 수정)

서버에서 실행되는 .bat 파일을 열어
아래와 같이 옵션 한 줄을 추가합니다.

📄 추가할 옵션

-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5100

 

이때 저는 5100번 포트번호를 임의로 써주었습니다. (사용하지 않고 있는 포트번호)

 이렇게 옵션을 추가하여 저장해주었습니다.

🔍 주요 옵션 설명

옵션의미

transport=dt_socket	디버깅 연결을 TCP 소켓으로 받겠다는 뜻
server=y	JVM이 디버거를 기다리는 서버 모드로 동작
suspend=y/n	y: 디버거가 붙을 때까지 실행 멈춤 / n: 그냥 바로 실행
address=0.0.0.0:5100	5100 포트로 모든 IP에서 접속 허용
-classpath	클래스 경로 지정

 

 

---

🖥️ 2. 서버 실행 및 확인

배치 파일을 더블클릭해 실행하면
콘솔에 다음과 같은 메시지가 떠야 합니다.

 

Listening for transport dt_socket at address: 5100

이게 보이면 디버그 포트가 정상적으로 열려서 5100번 포트에서 리스닝 중이라는 뜻입니다.

만약 포트 충돌 시에는 다른 포트를 사용해보세요.

---

🌐 3. 로컬 PC(Eclipse) 설정

Eclipse에서 아래 순서대로 설정합니다.

📋 설정 경로

 

Run → Debug Configurations → Remote Java Application → New Configuration

⚙️ 설정 내용

- 항목설정값

Project	디버깅할 프로젝트를 선택
Connection Type	Standard (Socket Attach)
Host	서버 IP
Port	5100 (서버에서 지정한 포트)

이렇게 설정하여 apply 해주고 Debug를 해주면 됩니다.

 

---

🚀 4. 디버그 시작

 

저 같은 경우 

위와 같은 Invalid thread access 라는 에러가 났습니다.

처음엔 포트나 방화벽 문제로 의심했지만, 포트도 잘 열려있었고 디버깅 직후 서버의 5100번 포트가 클라이언트와 연결은 되더라구요.

실제 원인은 이클립스가 디버그 실행 중 UI 스레드(SWT Display Thread) 를 잘못 접근했을 때 발생하는 예외.

⚙️ 원인 정리 

이클립스는 워크스페이스마다 .metadata 폴더를 가지고 있고, 그 안에 다음 정보들이 저장됩니다:

<workspace>/
 ├── .metadata/
 │   ├── .plugins/
 │   │   ├── org.eclipse.debug.core/
 │   │   ├── org.eclipse.e4.workbench/
 │   │   ├── org.eclipse.jdt.core/
 │   │   └── ...
 │   └── workspace.xml

이 폴더에는

• 디버그 레이아웃,
• Perspective(화면 배치),
• 내부 플러그인 캐시,
• 이전 디버그 세션 정보
  등이 모두 저장되는데

이게 꼬이거나, 오래된 플러그인 캐시가 남아 있으면 Eclipse가 UI 스레드에서 디버그 화면을 띄우는 순간 잘못된 스레드에서 SWT 호출이 일어나고 바로 예외가 터집니다.
→ 즉, “Invalid thread access”는 이 SWT 스레드 충돌 오류

 

 

아래는 제가 했던 방법들입니다.

(1) 새 Remote 설정 만들기

기존 설정이 깨진 상태일 수도 있으니 완전히 새로 만들어 보기:

• Run > Debug Configurations… > Remote Java Application > New Configuration
• Host / Port / Project 다시 지정 → Apply → 창 닫고 툴바에서 실행

>> 그래도 안됨

(2) 자바 jdk 버전 확인

서버와 버전이 안 맞다면 맞춰주세요

소스코드도 당연히 맞춰야하므로 맞는지 한번 더 확인해주었습니다.

 

>> 그래도 안됨

(3) Eclipse 캐시 정리

터미널이나 실행창에서:

 

"C:\Users\USER\eclipse\java-2024-09\eclipse\eclipse.exe" -clean

→ 내부 플러그인 캐시 초기화

 

>> 그래도 안됨

(4) 워크스페이스 .metadata 초기화

1. Eclipse 종료
2. <workspace>\.metadata\.plugins\org.eclipse.e4.workbench\ 폴더 삭제
3. Eclipse 재실행

→ UI 레이아웃/창 배치 정보가 초기화 후 새로 초기화된 레이아웃으로 열기

 

>> 그래도 안됨

 

(5)  새 워크스페이스

• File > Switch Workspace > Other… → 새 폴더 선택
• Import > Existing Projects into Workspace
• 다시 Remote 구성 새로 만들기

>> 됐음!

 

이렇게 새 워크스페이스로 프로젝트를 불러오면
.metadata 전체가 새로 생성되며,
깨진 캐시나 잘못된 플러그인 설정이 모두 초기화됩니다.

 

이 상태로 동일한 Remote Java Application 설정을 다시 만들면
에러 없이 정상적으로 디버깅이 시작됩니다.

 

 

🔍 왜 새 워크스페이스로 하면 되는가?

기존 워크스페이스의 .metadata 안에 저장된 이전 디버그 세션 정보나 UI 스레드 핸들이 꼬였기 때문

• Eclipse는 디버그 시 org.eclipse.debug.core 와 org.eclipse.e4.workbench 플러그인을 통해
  내부적으로 UI 스레드에서 SWT 컴포넌트를 갱신합니다.
• 그런데 이전 워크스페이스에서 플러그인 업데이트나 디버그 중단이 반복되면
  해당 핸들이 비정상적으로 남고, 다음 디버그 시 잘못된 스레드에서 UI를 접근하게 됩니다.
• 새 워크스페이스는 .metadata를 완전히 새로 만드므로
  UI 핸들, 디버그 레이아웃, 캐시가 모두 초기화되어 충돌이 사라집니다.

즉,

새 워크스페이스를 만들면 된다ㅡ는 말은 깨진 Eclipse 내부 캐시를 재설정하는 것과 같습니다.

---

💡 결론

• 문제 요약:
  Invalid thread access = Eclipse UI 스레드 충돌 (JDWP와 무관)
• 원인:
  기존 워크스페이스의 .metadata 내 캐시·플러그인 꼬임
• 해결:
  새 워크스페이스로 프로젝트를 가져오면 .metadata가 초기화되어 정상 작동

 

 

 

 

정상적으로 연결되면 콘솔에 이런 팝업이 뜹니다:

“This kind of launch is configured to open the Debug perspective when it suspends.”
→ [Switch] 클릭 (디버깅 모드 전환)

 

이제 서버에서 돌아가는 프로그램이
Eclipse 디버그 모드로 연결되며,
브레이크포인트가 걸리면서 로컬에서 원격으로 디버깅을 할 수 있게 됩니다.

 

---

5.  자주 발생하는 문제 & 해결법

- 증상원인해결

Connection refused	서버에서 포트 안 열림/이미 포트 사용 중	서버 콘솔에서 Listening... 확인
Connection timed out	방화벽 차단	서버 방화벽/포트 허용
Invalid thread access	Eclipse UI 스레드 버그	워크스페이스 새로 만들
UnsupportedClassVersionError	JDK 버전 불일치	서버/이클립스 모두 Java 8 클래스 파일로 맞추기
bind failed: Permission denied	원격 IP로 바인딩	address=0.0.0.0:포트 로 변경

---

6. 참고 명령어

 

Test-NetConnection 192.168.0.10 -Port 5100

• TcpTestSucceeded : True → Server(192.168.0.10)가 5100번 포트를 열고 있음

 

netstat -ano | findstr ":5100"

• LISTENING → 서버 포트 열림, 아직 클라이언트 접속 없음

 

 

---

🏁 요약

1. 서버 배치(.bat)파일에 -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=포트번호 추가
2. 서버 실행 후 콘솔에 Listening for transport... 확인
3. 로컬 Eclipse에서 Remote Java Application 생성(Debug Configurations > Remote Java Application > New Configuration)
4. Host/Port 설정 후 Apply 및 디버깅
5. 브레이크포인트로 원격 코드 제어