Chrome Inspector로 Android(AOS) 앱 디버깅 시 Offline 문제 해결 가이드

안드로이드 앱을 Chrome DevTools(Inspector) 로 디버깅하려고 할 때,
USB 디버깅까지 정상적으로 허용했는데도 다음과 같은 메시지가 나오며 연결되지 않는 경우가 있다.

Offline
Pending authentication: please accept debugging session on the device.

이 글에서는 해당 메시지가 의미하는 바와, 실제 현업에서 가장 많이 발생하는 원인들을 우선순위 기준으로 정리한다.

---

문제 증상 요약

• chrome://inspect 에서 단말이 Offline 상태로 표시됨
• USB 디버깅은 이미 허용됨
• adb 명령은 정상 동작하지만 Inspector 연결 불가

핵심 원인은 다음 한 줄로 요약할 수 있다.

USB 디버깅은 허용되었지만, WebView/Chrome 디버깅 세션 인증이 단말에서 완료되지 않음

---

1. 단말에서 디버깅 세션 허용 팝업 미승인 (가장 흔함)

USB 디버깅을 허용했더라도, Chrome / WebView 디버깅은 별도의 인증 팝업이 다시 뜰 수 있다.

체크 포인트

• 단말 화면이 켜져 있고 잠금 해제 상태인지
• 아래와 같은 팝업이 뒤에 숨어 있지 않은지
  • "이 컴퓨터의 디버깅을 허용하시겠습니까?"
  • "Chrome 디버깅을 허용"
• 팝업에서 [허용] + [항상 허용] 을 선택했는지

단말 화면을 끈 상태에서는 Inspector가 영원히 Pending authentication 상태로 남는다.

---

2. WebView 디버깅이 앱 코드에서 비활성화됨

앱이 WebView 기반이라면, 코드에서 디버깅을 명시적으로 활성화해야 한다.

필수 코드

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    WebView.setWebContentsDebuggingEnabled(true);
}

이 코드가 없으면?

• USB 디버깅: 정상
• adb: 정상
• Chrome Inspector: Offline + Pending authentication

사내 앱이나 자체 빌드 앱에서 특히 자주 빠지는 부분이다.

---

3. 앱이 WebView 기반이 아닌 경우

Chrome Inspector로 디버깅 가능한 대상은 다음뿐이다.

• Android Chrome 브라우저
• 디버깅이 활성화된 WebView

디버깅 불가능한 경우

• 순수 네이티브 앱 (WebView 미사용)
• WebView는 있으나 디버깅 비활성화 상태

이 경우 chrome://inspect 에서 대상 자체가 뜨지 않거나 Offline으로만 보인다.

---

4. adb 인증 캐시 꼬임

adb 키 인증이 꼬이면 Inspector에서 Offline 상태로 고정되는 경우가 있다.

해결 절차

adb kill-server
adb start-server
adb devices

그 다음 단말에서:

1. 개발자 옵션 → USB 디버깅 끄기
2. USB 디버깅 다시 켜기
3. 디버깅 허용 팝업 재승인

Android adb 다운로드 URL : https://developer.android.com/tools/releases/platform-tools?hl=ko 

---

5. Chrome / WebView 버전 불일치

PC Chrome과 단말 Chrome(WebView)의 버전 차이가 큰 경우 연결 실패 사례가 있다.

권장 사항

• PC: Chrome 최신 버전
• 단말:
  • Android System WebView 최신
  • Chrome 최신

---

6. 보안 정책 또는 Release 빌드 제한

사내 앱이나 운영 빌드에서는 디버깅 자체가 차단되는 경우도 많다.

확인 필요 항목

• android:debuggable="false"
• Release 빌드에서 WebView 디버깅 차단
• MDM / 보안 솔루션으로 USB 디버깅 제한

Inspector 디버깅은 debuggable=true 인 debug 빌드에서만 정상 동작하는 것이 원칙이다.

---

빠른 원인 체크리스트 (Top 6)

1. 단말 화면 ON + 디버깅 승인 팝업 확인
2. WebView.setWebContentsDebuggingEnabled(true) 적용 여부
3. adb devices 상태가 device 인지 확인
4. adb 서버 재시작
5. 앱이 WebView 기반인지 확인
6. Debug 빌드 여부 확인

---

마무리

Chrome Inspector의 Offline / Pending authentication 메시지는
대부분 단말 인증 또는 WebView 디버깅 설정 문제에서 발생한다.

특히 현업에서는 2번(WebView 디버깅 코드 누락) 이 가장 많은 원인이다.

같은 문제로 시간 낭비하지 않도록, 이 글을 체크리스트처럼 활용하길 바란다.