복군의 뒷주머니

OkHttp에 재시도 인터셉터를 달아 뒀는데 네트워크 실패가 전혀 줄지 않는다면, 재시도 조건이 실제 예외를 못 잡고 있을 가능성이 큽니다. 연결이 응답 도중 끊기면 OkHttp는 SocketException이 아니라 평범한 IOException에 unexpected end of stream이라는 문구를 실어 던지고, 읽기 타임아웃의 문구는 timeout이 아니라 Read timed out입니다. 제 앱은 두 구멍에 차례로 빠져 있었고, 실사용자 실패 9건의 재시도 기록이 9건 전부 "한 번에 포기"였습니다. 재시도 코드는 멀쩡히 붙어 있었는데 한 번도 돈 적이 없었던 것입니다.

공공데이터 API를 쓰는 앱이었습니다. 정부 서버가 가끔 연결을 끊어서, 몇 년 전에 재시도를 붙여 둔 코드가 있었습니다.

fun isRetryable(e: IOException): Boolean =
    e is SSLException ||
    e is SocketException ||
    e.message?.contains("Connection reset") == true ||
    e.message?.contains("timeout") == true

읽어 보면 그럴듯합니다. SSL 오류, 소켓 오류, 연결 리셋, 타임아웃. 흔한 네트워크 실패는 다 들어 있는 것처럼 보입니다. 파일 맨 위 주석에도 "서버의 Connection reset에 대비한 재시도"라고 적혀 있었습니다.

첫 번째 구멍 — unexpected end of stream

이 람다를 별도 클래스로 꺼내서 테스트를 붙였더니 첫 실행에서 바로 빨간불이 났습니다. 테스트는 MockWebServer로 서버가 연결을 진짜로 끊게 만든 것이었습니다.

server.enqueue(MockResponse().setSocketPolicy(SocketPolicy.DISCONNECT_AT_START))
server.enqueue(MockResponse().setBody("ok"))

client.newCall(request).execute().use { assertEquals(200, it.code) }

첫 요청은 끊기고 두 번째는 성공하니, 재시도가 돌면 통과해야 합니다. 그런데 첫 요청에서 예외가 그대로 밖으로 나왔습니다. 찍힌 예외는 이랬습니다.

java.io.IOException: unexpected end of stream on http://127.0.0.1:2114/...

SocketException이 아닙니다. 그냥 IOException이고, 문구에 "Connection reset"도 "timeout"도 없습니다. 네 조건 어디에도 걸리지 않으니 재시도 없이 즉시 포기했습니다. "서버가 연결을 끊는 상황"에 대비한 코드가 정작 그 상황의 상당 부분을 놓치고 있었습니다.

같이 터진 것 — android.util.Log는 JVM 테스트에서 예외를 던진다

처음 돌린 테스트 네 개가 전부 다른 이유로 깨지기도 했습니다. 재시도 경로의 catch 블록 안에 Log.w(...)가 있었는데, 로컬 유닛테스트에서 android.util.Log는 호출만 해도 RuntimeException: Method w in android.util.Log not mocked를 던집니다. 재시도 경로가 통째로 폭발한 것입니다.

unitTests.isReturnDefaultValues = true를 켜면 사라지긴 합니다. 저는 켜지 않았습니다. 그 옵션은 안드로이드 API 전부를 조용한 기본값으로 바꿔서, 언젠가 다른 곳의 진짜 실패까지 초록불로 덮기 때문입니다. 대신 로그를 생성자 파라미터로 뺐습니다.

internal class RetryInterceptor(
    private val maxAttempts: Int = 3,
    private val sleep: (Long) -> Unit = { Thread.sleep(it) },
    private val logWarn: (String) -> Unit = { Log.w(TAG, it) },   // 테스트에서는 {} 를 넘긴다
) : Interceptor

두 번째 구멍 — "timeout"과 "timed out"은 다른 문자열이다

unexpected end of stream을 조건에 추가해서 배포했습니다. 닷새 뒤, 실사용자 기기 세 종류에서 첫 실행 데이터 로딩 실패가 6건 올라왔습니다. 실패 사유는 timeout으로 정확히 분류돼 있었습니다. 그런데 같은 시간대의 재시도 결말 기록을 보니 이상했습니다.

실패 9건, 포기 9건. 모든 실패에서 재시도가 0회였습니다. 원문을 열어 보니 이렇게 찍혀 있었습니다.

retry_skipped  detail=1/3 timeout Read timed out

조건은 contains("timeout")인데 메시지는 Read timed out입니다. "timeout"과 "timed out"은 다른 문자열이라 걸리지 않습니다. 타입 조건에도 안 걸렸습니다. SocketTimeoutException은 이름과 달리 SocketException의 자식이 아니라 InterruptedIOException의 자식입니다.

java.io.IOException
 ├─ java.net.SocketException            ← 조건이 본 것
 │    └─ ConnectException ...
 └─ java.io.InterruptedIOException
      └─ java.net.SocketTimeoutException ← 실제로 온 것

더 허무했던 건, 같은 앱에서 실패 사유를 분류하는 코드는 진작 is SocketTimeoutException으로 정확히 분류하고 있었다는 점입니다. 그래서 보고서에는 reason=timeout이 제대로 찍혔습니다. 분류는 타입으로, 재시도 판정만 문자열로 한 불일치가 원인이었습니다.

이 옛 테스트가 결함을 덮고 있었다

타임아웃 테스트가 없었던 게 아닙니다. 있었고, 초록불이었습니다.

assertTrue(isRetryable(IOException("read timeout")))   // ← 손으로 만든 예외

첫 번째 구멍에서 "손으로 만든 예외로 테스트하면 안 된다"를 배우고도, 바로 그 파일에 그 함정이 한 줄 남아 있었습니다. SocketPolicy.NO_RESPONSE로 서버가 응답을 영영 안 주게 만들어 진짜 읽기 타임아웃을 내는 테스트로 바꿨습니다.

server.enqueue(MockResponse().setSocketPolicy(SocketPolicy.NO_RESPONSE))
server.enqueue(MockResponse().setBody("ok"))
// client 는 readTimeout 을 짧게(예: 200ms) 잡아 둔다

해결 — 판정을 문자열이 아니라 타입으로

fun isRetryable(e: IOException): Boolean =
    e is SocketTimeoutException ||      // "Read timed out" / "timeout" 둘 다
    e is SSLException ||
    e is SocketException ||
    e.message?.contains("unexpected end of stream", ignoreCase = true) == true

unexpected end of stream은 전용 예외 타입이 없어서 문구로 남길 수밖에 없습니다. 나머지는 전부 타입입니다. 실제로 실기기에서 타임아웃을 재현해 보니 같은 SocketTimeoutException인데 메시지가 Read timed out이 아니라 timeout으로 나왔습니다. 어느 계층이 먼저 터지느냐로 문구가 갈립니다(Okio의 타임아웃이냐, 소켓의 SO_TIMEOUT이냐). 문자열 판정은 기기와 경로에 따라 되고 안 되고가 갈린다는 뜻입니다.

함께 막아야 하는 두 가지

① 취소는 실패가 아니다. 코루틴이 취소되면 Retrofit이 Call.cancel()을 부르고, OkHttp는 IOException("Canceled")를 던집니다. 실패처럼 생겨서 옵니다. 그대로 두면 사용자가 화면을 벗어난 횟수만큼 실패 통계가 쌓입니다. 문구가 아니라 call의 상태로 가릅니다.

} catch (e: IOException) {
    if (chain.call().isCanceled()) throw e   // 재시도도, 실패 기록도 하지 않는다
    ...

② 타임아웃은 시도 상한을 따로 낮춘다. 끊긴 연결은 즉시 예외가 오지만, 타임아웃은 한 번마다 readTimeout을 꼬박 태웁니다. 20초 타임아웃에 3회면 최악 60초인데, 제 경우 그 실패가 나는 자리가 하필 첫 실행 스플래시였습니다. 타임아웃만 2회로 줄였고, 실기기에서 43초에 끝나는 것을 확인했습니다.

private fun attemptLimit(e: IOException) =
    if (e is SocketTimeoutException) minOf(maxAttempts, 2) else maxAttempts

재시도가 실제로 도는지 밖에서 보는 법

이번 일의 진짜 교훈은 여기 있습니다. 재시도는 잘 돌아도 조용하고, 안 돌아도 조용합니다. 실패 건수만 보면 "네트워크가 원래 불안정하구나"로 읽힙니다. 그래서 재시도의 결말을 세 갈래로 나눠 기록합니다.

첫 시도 성공은 기록하지 않습니다. 재시도가 있었을 때만 남겨야 "살려낸 요청"이 잡음에 묻히지 않습니다. 실패 건수와 skipped 건수가 똑같이 움직이면, 그게 재시도가 한 번도 안 돌고 있다는 지문입니다.

정리

• 연결이 응답 도중 끊기면 OkHttp는 평범한 IOException("unexpected end of stream on …")을 던집니다. SocketException 조건에 안 걸립니다.
• 읽기 타임아웃의 문구는 Read timed out이라 contains("timeout")에 안 걸립니다. SocketTimeoutException은 SocketException의 자식도 아닙니다.
• 판정은 타입으로 합니다. 같은 예외라도 계층에 따라 문구가 달라집니다.
• 테스트는 MockWebServer의 SocketPolicy로 진짜 소켓을 끊어서 합니다. 손으로 만든 예외는 아무것도 검증하지 않습니다.
• 수정을 잠깐 되돌려서 새 테스트가 빨간불이 되는지 확인하세요. 초록불이 "검증됐다"인지 "조건에 못 닿았다"인지는 그렇게만 갈립니다.
• 재시도 결말(recovered·exhausted·skipped)을 기록하세요. 안 도는 재시도는 로그 없이는 안 보입니다.

자주 묻는 것

OkHttp의 retryOnConnectionFailure로는 안 되나요?

기본값이 true이고 일부 연결 실패는 알아서 다시 시도합니다. 하지만 대상이 좁습니다. 이미 요청을 보낸 뒤 응답 도중 끊긴 경우나 읽기 타임아웃은 다시 보내지 않는 경우가 많습니다. 서버 쪽에서 중복 처리돼도 문제없는 GET 요청이라면 인터셉터로 직접 재시도하는 편이 확실합니다.

POST도 이렇게 재시도해도 되나요?

조심해야 합니다. unexpected end of stream은 서버가 요청을 이미 처리한 뒤 응답만 못 보낸 경우에도 납니다. 결제·등록 같은 요청을 다시 보내면 두 번 처리될 수 있습니다. 저는 조회용 GET에만 이 인터셉터를 붙였습니다.

unexpected end of stream이 자꾸 나는 원인 자체는 뭔가요?

대개 서버나 중간 장비(로드밸런서·프록시)가 연결을 먼저 닫은 것입니다. 오래 놀던 keep-alive 연결을 재사용하려는 순간 서버는 이미 닫아 둔 경우가 흔합니다. 서버를 고칠 수 없는 공공 API라면 클라이언트에서 재시도로 받아내는 것이 현실적인 답입니다.

GA4에 커스텀 측정기준을 등록해 뒀는데 보고서를 열면 값이 하나도 안 담기고 (not set)만 나오는 경우가 있습니다. 대개는 수집이 안 되는 게 아니라 파라미터 타입 문제입니다. 측정기준은 문자열만 읽기 때문에, putLong으로 보낸 숫자는 등록해 둬도 값이 통째로 비어 있습니다. 제 앱 네 개가 전부 그 상태였고 30일치 1,209건이 남김없이 (not set)이었는데, 이벤트 수는 정확하게 나오는 탓에 한참 동안 눈치채지 못했습니다.

어쩌다 그렇게 됐는지부터 적겠습니다. 앱에 계측을 심었습니다. 목록 화면이 열릴 때 몇 건이 실렸는지 같이 보내도록 했습니다.

val params = Bundle().apply {
    putString("source", "cache")
    putLong("item_count", list.size.toLong())   // 몇 건 실렸나
}
FirebaseAnalytics.getInstance(context).logEvent("home_loaded", params)

GA4 관리 화면에서 item_count를 커스텀 측정기준으로 등록했습니다. 며칠 기다렸다가 탐색 보고서를 열었습니다.

item_count        이벤트 수
(not set)              1,209
─────────────────────────────
합계                    1,209

전량 (not set)이었습니다. 한 건도 값이 담기지 않았습니다. 이벤트 수 1,209는 정확했습니다. 즉 이벤트는 제대로 나가고 있었고, 값만 비어 있었습니다.

원인 — 측정기준은 문자열만 읽는다

GA4의 커스텀 측정기준(dimension)은 문자열 파라미터만 읽습니다. putLong·putDouble·putInt로 보낸 숫자는 측정기준으로 등록해 둬도 조회하면 전부 (not set)입니다.

GA4가 파라미터를 받는 창구는 두 개인데, 서로 통하지 않습니다.

등록 화면에서는 이 구분이 눈에 잘 안 들어옵니다. 파라미터 이름을 적는 칸이 똑같이 생겼고, 타입이 안 맞아도 등록은 그냥 됩니다. 경고도 없습니다.

진짜 무서운 것은 실패하는 방식이다

저는 이걸 한참 뒤에 알았습니다. 하필 item_count를 쓰던 검사가 "목록이 빈 채로 화면이 떴는가"를 잡는 것이었습니다. 예전에 목록이 통째로 비어 나가는 사고가 있었고, 그 재발을 감지하려고 심어 둔 계측이었습니다.

그런데 값이 전부 (not set)이니 item_count = 0인 건이 한 건도 잡히지 않습니다. 검사는 매번 "이상 없음"을 반환했습니다. 그 검사는 한 번도 돈 적이 없었던 셈입니다.

제 앱들을 전수로 훑어봤더니 item_count를 보내는 앱 네 개가 전부 같은 상태였습니다. 한 곳을 잘못 짠 게 아니라, 같은 코드를 베껴 쓰면서 같은 오해가 그대로 복사돼 있었습니다.

해결 — 숫자를 구간 문자열로 바꿔 보낸다

값별로 쪼개서 세고 싶다면 숫자를 구간으로 묶은 문자열로 보냅니다.

// ❌ 측정기준으로는 영영 안 읽힌다
putLong("item_count", list.size.toLong())

// ✅ 구간 문자열
putString("item_count", bucketOf(list.size))

private fun bucketOf(n: Int): String = when {
    n <= 0    -> "0"        // ← 이게 잡고 싶었던 값이다
    n < 10    -> "1_9"
    n < 50    -> "10_49"
    n < 100   -> "50_99"
    else      -> "100_plus"
}

구간을 나눌 때 가장 중요한 경계를 독립된 칸으로 두는 것이 핵심입니다. 저에게 필요했던 건 "0건"이었으므로 "0"을 따로 뺐습니다. "0_9"로 묶었다면 고쳐도 여전히 못 셌을 겁니다.

측정항목으로 등록하면 되는 것 아닌가

그것도 답이 아닙니다. 실제로 그렇게 해 봤는데, 커스텀 측정항목은 합계와 평균만 내줍니다. "총 3,400건"은 알려주지만 "0건이 몇 번이었나"는 못 셉니다. 제가 알고 싶었던 건 뒤쪽이었습니다.

둘 다 필요하면 둘 다 보내면 됩니다. 파라미터 이름만 다르게 해서 한 이벤트에 같이 싣습니다.

putString("item_count", bucketOf(n))   // 측정기준 — 구간별로 센다
putLong("item_total", n.toLong())      // 측정항목 — 합계·평균을 낸다

확인하는 법 — 코드를 읽지 말고 로그를 보세요

이 결함은 코드를 읽으면 정상으로 보입니다. 유닛테스트도 릴리스 빌드 확인도 잡아 주지 않습니다. 이벤트가 안 나가는 것도 아니고, 값이 틀린 것도 아니고, 타입이 안 맞을 뿐이기 때문입니다.

실기기에서 Firebase Analytics의 디버그 로그를 직접 보는 게 가장 확실합니다.

adb shell setprop log.tag.FA VERBOSE
adb shell setprop log.tag.FA-SVC VERBOSE
adb shell setprop debug.firebase.analytics.app 내.패키지.이름

adb logcat -d -s FA FA-SVC | findstr "Logging event"

파라미터가 타입까지 그대로 찍혀 나옵니다.

Logging event: origin=app, name=home_loaded,
  params=Bundle[{source(_o)=cache, item_count(_o)=3}]      ← 숫자로 나가는 중
  params=Bundle[{source(_o)=cache, item_count(_o)=1_9}]    ← 문자열로 고친 뒤

값이 따옴표 없이 3으로 찍히면 숫자, 1_9처럼 문자열 형태면 제대로 나가는 중입니다.

같은 계열의 함정 하나 더

실패 원인을 보낼 때 예외 클래스 이름을 그대로 싣는 코드도 같은 방식으로 조용히 망가집니다.

// ❌ 릴리스에서 이름이 뭉개진다
putString("reason", e::class.simpleName ?: "unknown")

릴리스는 isMinifyEnabled = true라 라이브러리와 우리 예외의 클래스 이름이 한 글자로 줄어듭니다. 저는 보고서에서 reason=X를 봤습니다. 그날 무엇이 실패했는지는 영영 못 읽습니다. JDK 내장 예외는 난독화를 피해 살아남기 때문에 되는 앱과 안 되는 앱이 갈려 더 헷갈립니다. 게다가 그 한 글자는 빌드마다 바뀌어서 집계 자체가 성립하지 않습니다.

is 타입 검사로 고정 키를 만들어 보내야 합니다.

fun reasonOf(e: Throwable): String = when (e) {
    is java.net.UnknownHostException -> "no_network"
    is java.net.SocketTimeoutException -> "timeout"
    is javax.net.ssl.SSLException -> "ssl"
    is java.io.IOException -> "io"
    else -> "unknown"
}

순서에 주의합니다. SocketTimeoutException은 IOException의 하위 타입이라 좁은 것을 먼저 놓지 않으면 전부 "io"로 뭉쳐집니다.

정리

• GA4 커스텀 측정기준은 문자열만 읽습니다. putLong으로 보낸 숫자는 등록해도 전부 (not set)입니다.
• 타입이 안 맞아도 등록은 되고 경고도 없습니다. 이벤트 수는 맞게 나와서 대시보드가 멀쩡해 보입니다.
• 값별로 세려면 구간 문자열로 보내고, 가장 중요한 경계는 독립된 칸으로 둡니다.
• 합계도 필요하면 측정항목용 숫자를 따로 하나 더 보냅니다.
• 검증은 실기기에서 adb logcat -s FA FA-SVC로 합니다. 코드를 읽어서는 안 보입니다.
• 계측을 심은 것과 밖에서 읽히는 것은 다릅니다. GA4에서 그 값을 실제로 꺼내 보는 데까지가 한 작업입니다.

자주 묻는 것

등록하고 얼마나 기다려야 값이 보이나요?

커스텀 측정기준은 등록한 이후에 수집된 데이터부터 적용됩니다. 소급되지 않습니다. 보고서에 반영되기까지 보통 24-48시간 걸리므로, 하루 이틀은 (not set)이 정상입니다. 이 글의 증상은 며칠이 지나도 100%가 (not set)인 경우입니다. 급하게 확인하려면 DebugView를 쓰면 실시간으로 보입니다.

이벤트당 파라미터 개수 제한이 있나요?

이벤트 하나에 파라미터 25개까지이고, 속성 단위로 커스텀 측정기준은 이벤트 범위 50개, 측정항목은 50개까지 등록할 수 있습니다. 실무에서는 개수보다 이름을 앱마다 다르게 쓰는 것이 먼저 문제가 됩니다. 같은 사건이 앱마다 다른 파라미터 이름으로 들어오면 한 화면에서 못 묶습니다.

등록할 때 표시 이름은 아무렇게나 지어도 되나요?

표시 이름에 괄호를 넣지 마세요. 여러 개를 한 번에 등록할 때 괄호가 들어간 것만 조용히 빠지는 일을 겪었습니다. 오류 메시지는 나오지 않고, 등록 목록에서 하나가 없을 뿐입니다. 등록 직후에 목록을 다시 읽어 개수를 세어 보는 것을 권합니다.

다른 버그를 잡다가 계측 테스트를 Android 10 실기기에서 돌렸습니다. 평소에는 최신 기기로만 돌리던 것이었습니다.

java.lang.SecurityException: Unknown permission
    android.permission.READ_MEDIA_IMAGES

갤러리 테스트 세 건이 전부 이걸로 죽었습니다. 테스트가 실패한 게 아니라 본문이 시작조차 못 한 것입니다.

범인은 이 줄이었습니다.

// ❌ API 33 전용 권한을 모든 기기에 요구한다
@get:Rule(order = 0)
val permissionRule: GrantPermissionRule = GrantPermissionRule.grant(
    Manifest.permission.CAMERA,
    Manifest.permission.ACCESS_FINE_LOCATION,
    Manifest.permission.READ_MEDIA_IMAGES,
)

원인 — 권한 이름이 API 33에서 갈린다

READ_MEDIA_IMAGES는 API 33(Android 13)에서 생긴 권한입니다. 그 미만 기기에는 그런 이름의 권한이 시스템에 아예 없습니다.

GrantPermissionRule은 테스트 본문 전에 이 권한들을 부여하려 하는데, 존재하지 않는 이름을 받으면 SecurityException을 던집니다. @Rule 단계에서 던지므로 @Before도 @Test도 실행되지 않습니다.

여기서 정신이 번쩍 들었던 건, 제 앱의 minSdk가 26이라는 사실이었습니다. 즉 갤러리 기능은 지원 범위의 상단 일부에서만 검증돼 왔습니다. 그 아래 구간은 테스트가 존재는 하는데 한 번도 돌아 본 적이 없었습니다.

고치는 법 — 매니페스트와 같은 경계로 가른다

@get:Rule(order = 0)
val permissionRule: GrantPermissionRule = GrantPermissionRule.grant(
    Manifest.permission.CAMERA,
    Manifest.permission.ACCESS_FINE_LOCATION,
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU)
        Manifest.permission.READ_MEDIA_IMAGES
    else
        Manifest.permission.READ_EXTERNAL_STORAGE
)

더 나쁜 쪽 — 아무것도 검증하지 않으면서 늘 통과하던 테스트

위의 건은 그래도 빨간불이라 눈에 띕니다. 같은 날 발견한 다른 테스트가 훨씬 나빴습니다.

// ❌ "갤러리로 이동했는가"를 본다면서 빈 목록 문구를 확인한다
@Test
fun galleryContent_shown_afterOpeningGallery() {
    composeTestRule.onNodeWithContentDescription("갤러리").performClick()
    composeTestRule.onNodeWithText("저장된 사진이 없습니다").assertIsDisplayed()
}

이 테스트는 계속 통과하고 있었습니다. 이유가 문제입니다. 그 테스트 클래스는 사진 읽기 권한을 부여하지 않았고, 그래서 갤러리는 사진이 있든 없든 늘 비어 보였습니다.

즉 이 테스트는

• 화면 이동을 검증한다고 이름을 붙였지만
• 실제로는 목록이 비어 있는지를 보고 있었고
• 권한이 없어서 영원히 비어 있었습니다

실패할 수 없는 초록불이었습니다. 권한을 제대로 넣자마자 곧바로 빨간불이 됐습니다.

고친 방식은 관심사에 맞는 것을 보게 한 것입니다. 이동을 확인하고 싶으면 목록 내용이 아니라 탭이 선택됐는지를 봅니다.

@Test
fun galleryScreen_retainsStateAfterTabSwitch() {
    composeTestRule.onNodeWithText(str(R.string.tab_settings)).performClick()
    composeTestRule.waitForIdle()
    composeTestRule.onNodeWithText(str(R.string.tab_gallery)).performClick()
    composeTestRule.waitForIdle()
    // "무엇이 떴는가"가 아니라 "갤러리로 돌아왔는가"가 이 테스트의 관심사다
    composeTestRule.onNodeWithText(str(R.string.tab_gallery)).assertIsSelected()
}

"빈 상태"를 전제하는 테스트는 실패가 아니라 스킵이어야 한다

빈 목록 문구를 진짜로 확인하고 싶은 테스트도 물론 있습니다. 그건 기기에 사진이 없을 때만 성립하는 전제입니다. 사진이 있는 실기기에서 빨간불로 두면 진짜 회귀와 구분이 안 됩니다.

@Test
fun galleryScreen_showsEmptyMessageWhenNoPhotos() {
    assumeTrue("사진이 있는 기기에서는 빈 상태를 볼 수 없다", galleryIsEmpty())
    composeTestRule.onNodeWithText(str(R.string.gallery_empty)).assertIsDisplayed()
}

전제 판정은 화면과 같은 질의를 재사용한다

galleryIsEmpty()를 짤 때 경로를 테스트에 따로 적고 싶어집니다. 그러면 앱이 저장 폴더를 바꿨을 때 조용히 어긋납니다. 화면이 쓰는 질의 함수를 그대로 가져다 씁니다.

private fun galleryIsEmpty(): Boolean {
    val (selection, args) = galleryQuery(Build.VERSION.SDK_INT)   // 화면과 같은 질의
    val ctx = InstrumentationRegistry.getInstrumentation().targetContext
    val cursor = ctx.contentResolver.query(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
        arrayOf(MediaStore.Images.Media._ID), selection, args, null
    ) ?: return true
    cursor.use { return it.count == 0 }
}

무엇을 놓쳤나

이 테스트들이 못 잡고 지나간 것이 실제로 있었습니다. 같은 앱에서 SQLiteException: no such column: relative_path로 갤러리를 여는 순간 앱이 죽는 버그가 API 28 이하에 있었습니다. MediaStore.RELATIVE_PATH가 API 29부터인데 minSdk가 26이었던 것입니다.

갤러리 화면을 여는 계측 테스트가 분명히 있었는데도 못 잡았습니다. 그 테스트가 API 33 이상에서만 돌고 있었기 때문입니다. 자세한 내용은 따로 정리했습니다 — (MediaStore relative_path 편).

일반화 — 초록불의 두 가지 뜻

이번 일을 한 문장으로 줄이면 이렇습니다.

초록불이 "검증됐다"는 뜻인지 "조건에 못 닿았다"는 뜻인지 갈라 봐야 합니다.

아래는 전부 결과 요약에서 통과처럼 보이는 것들입니다.

결과

권한 분기를 넣고 단정문을 바로잡은 뒤 두 환경에서 돌렸습니다.

실기기(Android 10) : 계측 42개 · 0 실패 · 2 스킵
에뮬레이터(전면 카메라 없음) : 계측 42개 · 0 실패 · 1 스킵

스킵 수가 환경마다 다른 것이 정상입니다. 그 차이가 곧 "이 환경에서는 어떤 전제가 성립하지 않았는가"를 말해 줍니다. 스킵이 0으로만 나오면 오히려 전제 처리를 안 한 것일 수 있습니다.

정리

• GrantPermissionRule에 API 33 전용 권한 이름을 그대로 넘기지 마세요. 33 미만에서 SecurityException으로 본문이 시작조차 못 합니다.
• 권한 목록의 경계는 매니페스트의 maxSdkVersion과 같게 맞춥니다.
• 권한을 안 준 테스트는 화면이 늘 비어 보여 아무거나 통과시킵니다.
• "빈 상태" 전제는 실패가 아니라 스킵(assumeTrue)으로 처리합니다.
• 전제 판정은 화면과 같은 질의를 재사용합니다.
• 테스트도 minSdk에서 한 번 돌리세요. 앱을 돌린 것과는 별개의 확인입니다.

자주 묻는 것

CI에서는 최신 API 에뮬레이터만 쓰는데요?

흔한 구성이고, 그래서 이 문제가 오래 숨습니다. 전체 스위트를 두 배로 돌릴 필요는 없습니다. 저장소·권한·미디어를 건드리는 테스트 클래스만 minSdk 에뮬레이터에서 한 번 더 돌려도 이 부류는 걸러집니다.

@SdkSuppress로 33 미만을 제외하면 안 되나요?

그건 "33 미만에서는 검증하지 않겠다"고 선언하는 것입니다. 기능 자체가 33+ 전용이면 옳은 선택이지만, 갤러리처럼 minSdk 전 구간에서 동작해야 하는 기능에 쓰면 문제를 감추는 쪽이 됩니다. 제 경우가 정확히 그랬습니다.

connectedAndroidTest로 돌리면 권한이 자꾸 초기화되는데요?

connectedAndroidTest는 앱을 설치하면서 권한 상태를 지웁니다. 저는 설치 → pm grant → am instrument 순서로 나눠 돌립니다. GrantPermissionRule과 별개로, 테스트 밖에서 미리 필요한 권한을 주고 시작하는 편이 결과가 안정적입니다.

카메라 화면에 로그를 심어 두고 며칠 뒤 이런 것을 봤습니다.

camera/bind_failed —
IllegalArgumentException: No available camera can be found lens=0

lens=0은 CameraSelector.LENS_FACING_FRONT, 즉 전면입니다. 전면 카메라가 없는 기기에서 전환 버튼을 누른 것입니다.

여기까지는 예상 가능한 범위입니다. 진짜 문제는 그 다음이었습니다. 실패한 것은 전면인데, 잘 나오던 후면 미리보기까지 검은 화면이 됩니다. 그리고 그 상태에서 빠져나올 방법이 없습니다. 크래시가 아니라서 아무 안내도 없고, 사용자는 이유 없는 검은 화면만 봅니다.

왜 후면까지 죽는가 — 순서 문제다

문제가 된 코드는 흔한 모양이었습니다.

// ❌ 떼고 나서 붙이는데, 붙이기가 실패하면 아무것도 안 남는다
LaunchedEffect(lensFacing) {
    val provider = ProcessCameraProvider.getInstance(context).get()
    val selector = CameraSelector.Builder().requireLensFacing(lensFacing).build()

    provider.unbindAll()
    provider.bindToLifecycle(lifecycleOwner, selector, preview, imageCapture)
}

unbindAll()이 먼저입니다. 이 줄을 지나는 순간 기존에 잘 붙어 있던 후면 바인딩이 사라집니다. 그리고 다음 줄에서 없는 렌즈로 붙이려다 예외가 납니다. 남는 상태는 "아무것도 안 붙은 상태"입니다.

즉 전환 한 번의 실패가 카메라 기능 전체를 끕니다.

게다가 재시도가 없다

LaunchedEffect(lensFacing)은 키가 바뀔 때만 다시 돕니다. 실패해도 lensFacing은 여전히 전면 값 그대로이므로, 이 블록은 다시 실행되지 않습니다. 복구 경로가 아예 없는 것입니다. 화면을 나갔다 들어와도 상태가 남아 있으면 그대로입니다.

고친 방식 — 떼기 전에 확인하고, 실패하면 되돌린다

세 겹으로 얽힌 문제라 세 군데를 고쳤습니다.

① 있는지 먼저 묻는다 — unbindAll()을 지나기 전에

val provider = ProcessCameraProvider.getInstance(context).get()

// 두 렌즈가 다 있을 때만 전환 버튼을 띄운다
canSwitch = provider.hasCamera(CameraSelector.DEFAULT_BACK_CAMERA) &&
            provider.hasCamera(CameraSelector.DEFAULT_FRONT_CAMERA)

val selector = CameraSelector.Builder().requireLensFacing(lensFacing).build()

// ⚠️없는 렌즈라면 unbindAll() 을 지나기 전에 돌아선다
if (!provider.hasCamera(selector)) {
    if (lensFacing != boundLens) {
        lensFacing = boundLens        // 전환 실패 — 되던 렌즈로 되돌린다
    } else if (!flippedOnce) {
        flippedOnce = true            // 처음 고른 렌즈가 없다 — 반대쪽을 한 번만
        lensFacing = otherLens(lensFacing)
    }
    return@LaunchedEffect
}

hasCamera(selector)가 핵심입니다. 떼기 전에 물어보면 잘 붙어 있던 것을 잃지 않습니다.

② 실패해도 되돌아갈 자리를 기억한다

// 마지막으로 **실제 바인딩에 성공한** 렌즈. 전환이 실패했을 때 되돌아갈 자리다.
var boundLens by remember { mutableIntStateOf(CameraSelector.LENS_FACING_BACK) }

// ... 바인딩 성공 직후에만 갱신한다
provider.unbindAll()
provider.bindToLifecycle(lifecycleOwner, selector, preview, imageCapture)
boundLens = lensFacing

lensFacing(가고 싶은 곳)과 boundLens(실제로 성공한 곳)를 따로 둡니다. 하나로 합쳐 두면 "되돌릴 자리"라는 정보 자체가 없습니다.

그리고 catch에서도 되돌립니다. 되돌리면 lensFacing이 바뀌므로 LaunchedEffect가 다시 돌아 미리보기가 살아납니다.

} catch (e: Exception) {
    // 기록만 하고 끝내면 재시도 자체가 없다 — 검은 화면이 그대로 남는다
    logIssue("camera", "bind_failed", "${e::class.simpleName}: ${e.message} lens=$lensFacing")
    if (lensFacing != boundLens) lensFacing = boundLens
}

③ 없는 렌즈로 가는 버튼을 아예 안 띄운다

if (canSwitch) {
    IconButton(onClick = { lensFacing = otherLens(lensFacing) }) { /* ... */ }
}

무한 왕복 빗장

flippedOnce가 왜 필요한지 짚고 갑니다. 처음 고른 렌즈가 없어서 반대쪽으로 넘겼는데 그쪽도 없으면, 다시 반대쪽으로 넘기면서 두 렌즈 사이를 무한히 왕복합니다. 카메라가 아예 없는 기기에서 실제로 그렇게 됩니다. 한 번만 넘겨 보고 멈추게 해야 합니다.

검증 — 실기기로는 이 버그를 못 잡는다

여기가 제가 얻은 가장 큰 교훈입니다. 제 테스트 폰은 전면과 후면이 다 있어서 문제의 분기에 아예 들어가지 않습니다. 몇 번을 눌러 봐도 정상입니다.

조건을 만들어야 합니다. 에뮬레이터를 전면 카메라 없이 띄웁니다.

emulator -avd Pixel_5_API_30 -camera-front none

제대로 걸렸는지 확인합니다.

adb shell dumpsys media.camera | findstr /C:"Number of camera devices" /C:"Facing"

Number of camera devices: 1
Facing: Back

음성 대조군을 반드시 확인하세요

테스트를 짜고 초록불이 떴다고 끝내면 안 됩니다. 수정 전 코드를 같은 에뮬레이터에 올려서 빨간불이 뜨는지 봐야 합니다. 저는 이렇게 확인했습니다.

전면=false 후면=true 인데 전환 버튼 1개  → 실패

이게 나와야 그 테스트가 실제로 이 버그를 잡는다는 게 증명됩니다. 대조군 없이 통과만 보면, 조건에 못 닿아서 초록불인 경우와 구분되지 않습니다.

정리

• unbindAll()은 돌아올 수 없는 지점입니다. 그 앞에서 hasCamera()로 확인하세요.
• "가고 싶은 렌즈"와 "실제로 성공한 렌즈"를 따로 들고, 실패하면 되돌려 LaunchedEffect를 다시 돌립니다.
• getInstance().get()을 try 안에 넣으세요. 일시적 점유에도 던집니다.
• 실패를 기록하세요. 크래시가 아닌 고장은 로그를 안 심으면 영영 모릅니다.
• 없는 렌즈로 가는 버튼 자체를 감추고, 무한 왕복 빗장을 겁니다.
• 검증은 -camera-front none 에뮬레이터 + 음성 대조군으로 합니다.

자주 묻는 것

전면 없는 기기가 요즘 있나요?

제 실사용자 중에는 없었습니다. 이 로그를 낸 것도 자동 검사 기기와 에뮬레이터였습니다. 그래도 고친 이유는 같은 코드 경로를 실사용자 상황이 공유하기 때문입니다. 다른 앱이 카메라를 점유한 순간 전환을 누르면 똑같이 검은 화면에 갇힙니다. 지표가 0인 것과 코드가 맞는 것은 다릅니다.

DEFAULT_FRONT_CAMERA로 바인딩하면 알아서 폴백되지 않나요?

requireLensFacing은 이름 그대로 필수 조건이라 없으면 예외입니다. 자동 폴백을 기대하고 짜면 이 글의 상황이 그대로 재현됩니다.

화면에 안내를 띄우는 게 낫지 않나요?

둘 다 하는 게 맞습니다. 다만 먼저 할 것은 미리보기를 살리는 것입니다. "전면 카메라가 없습니다"만 띄우고 검은 화면을 그대로 두면 사용자는 여전히 아무것도 못 합니다.

설정 화면에 텍스트 입력 칸을 하나 만들었습니다. 값은 DataStore에 저장하고, 화면은 그 값을 collectAsState()로 받아 씁니다. 교과서적인 단방향 데이터 흐름입니다.

영어로 hello를 칩니다. 잘 됩니다. 지우고 다시 칩니다. 잘 됩니다. 배포합니다.

그리고 며칠 뒤 한글로 "가나"를 쳐 봅니다.

입력한 것 : 가나
칸에 남은 것 : ㄱㅏㄴㅏ

자음과 모음이 합쳐지지 않고 낱개로 확정됩니다. 백스페이스도 자모 단위로 지워집니다. 저는 이 상태로 앱을 스토어에 내보냈고, 그 입력 칸은 앱의 핵심 기능이었습니다.

원인 — 한 글자마다 디스크를 한 바퀴 돈다

문제의 코드는 이렇게 생겼습니다.

// ❌ 값의 주인이 DataStore 다
val settings by settingsVm.settings.collectAsState()

OutlinedTextField(
    value = settings.customText,
    onValueChange = { settingsVm.setCustomText(it) },
)

한 글자를 칠 때마다 이 경로를 돕니다.

키 입력 → onValueChange → ViewModel → DataStore 쓰기(디스크)
       → Flow 방출 → collectAsState → 리컴포지션 → value 갱신

영어에서는 이 왕복이 늦어도 티가 안 납니다. h는 그냥 h이고, 늦게 돌아와도 h입니다.

한글은 다릅니다. 한글 입력은 "조합 중"이라는 중간 상태를 거칩니다. ㄱ → 가 → 간처럼 이미 화면에 있는 글자가 다음 입력으로 바뀌는 과정이고, 이 조합 상태는 IME가 입력 필드와 연결된 채로 들고 있습니다.

그런데 value가 비동기 저장소에서 돌아오는 값이면, 한 글자마다 필드의 값이 외부에서 통째로 교체됩니다. IME 입장에서는 자기가 조합하던 글자가 매번 발밑에서 사라지는 셈이라 조합 상태가 끊깁니다. 끊긴 조합은 ㄱ인 채로 확정되고, 다음 ㅏ도 따로 확정됩니다. 그래서 ㄱㅏㄴㅏ가 됩니다.

해결 — 입력값은 화면이 들고, 저장은 따로 내보낸다

고치는 원칙은 한 줄입니다. 입력 중인 값의 주인은 화면이어야 합니다. 저장은 그대로 나가되, 필드가 그 결과를 기다리지 않게 만듭니다.

// ✅ 입력값은 화면이 직접 들고 있는다
var customInput by rememberSaveable { mutableStateOf<String?>(null) }

OutlinedTextField(
    value = customInput ?: settings.customText,
    onValueChange = {
        customInput = it              // 화면이 즉시 반영 — IME 조합이 안 끊긴다
        settingsVm.setCustomText(it)  // 저장은 따로 나간다
    },
    singleLine = true,
)

String?과 null이 하는 일

null은 "아직 사용자가 아무것도 안 쳤다"는 뜻입니다.

빈 문자열("")로 초기화하면 안 되는 이유가 여기 있습니다. DataStore가 값을 늦게 내주는 첫 프레임에서 저장돼 있던 글자가 빈 칸으로 덮여 보입니다. 사용자에게는 설정이 날아간 것처럼 보입니다.

remember가 아니라 rememberSaveable

remember만 쓰면 화면 회전이나 시스템의 프로세스 정리에서 입력 중이던 값이 사라집니다. rememberSaveable은 Bundle에 실려 살아남습니다. 입력 칸에는 기본으로 이쪽을 씁니다.

같은 함정이 있는 자리들

DataStore만의 문제가 아닙니다. value가 비동기 왕복을 거쳐 돌아오면 전부 같습니다.

• Room — 입력할 때마다 DB에 쓰고 Flow로 다시 받는 구조
• 서버 저장 — 자동 저장 필드. 네트워크 지연이라 증상이 가장 심합니다
• ViewModel StateFlow — 저장소가 없어도 debounce·distinctUntilChanged·stateIn 같은 연산자가 중간에 끼면 같은 일이 벌어집니다
• 부모에서 내려주는 상태 호이스팅 — 값이 여러 단계를 거쳐 오면서 프레임이 밀리는 경우

확인하는 법

도구가 필요 없습니다. 앱을 켜고 텍스트 칸에 한글을 치면 끝입니다. 문제는 그걸 안 해 본다는 것입니다.

체크리스트로 두면 좋습니다.

• 입력 칸마다 "가나다"를 실제로 쳐 본다 — 붙여넣기 말고 자판으로. 붙여넣기는 조합 과정이 없어 통과합니다
• 중간 글자를 백스페이스로 지웠다가 다시 친다 — 조합 상태가 가장 잘 깨지는 지점입니다
• 빠르게 연타해 본다 — 저장이 느릴수록 증상이 선명합니다
• 화면을 회전시킨다 — rememberSaveable 여부가 여기서 드러납니다

UI 테스트로 잡으려는 시도는 권하지 않습니다. Compose 테스트의 텍스트 입력은 조합 과정을 거치지 않고 값을 밀어 넣는 방식이라, 사람이 손으로 치는 것과 경로가 다릅니다. 초록불이 나와도 손으로 치면 깨집니다.

정리

• Compose TextField의 value를 비동기 저장소 왕복에 맡기면 한글 자모가 흩어집니다.
• 원인은 성능이 아니라 IME 조합 상태가 매 글자 끊기는 것입니다.
• 입력값은 rememberSaveable로 화면이 들고, 저장은 따로 내보냅니다.
• null 초기값으로 "아직 안 침"과 "빈 값"을 구분합니다.
• 텍스트 입력 칸이 있으면 반드시 한글로 쳐 보세요. 영어 테스트는 이 버그를 절대 못 잡습니다.

자주 묻는 것

매 글자 저장하는 게 문제 아닌가요? debounce를 걸면 되지 않나요?

debounce는 저장 횟수를 줄일 뿐, value의 주인이 여전히 저장소면 조합은 똑같이 끊깁니다. 오히려 지연이 들쭉날쭉해져 증상이 불규칙해집니다. 두 가지는 별개의 개선이고, 먼저 고칠 것은 값의 주인입니다. 주인을 화면으로 옮긴 뒤에 저장 쪽에 debounce를 거는 것은 좋습니다.

TextFieldValue를 쓰면 해결되나요?

TextFieldValue는 커서 위치·선택 영역까지 같이 다루는 타입이라 관리할 상태가 늘어납니다. 원인이 "값이 외부에서 교체된다"는 것이므로, 타입을 바꾸는 게 아니라 주인을 바꿔야 풀립니다.

단방향 데이터 흐름 원칙에 어긋나는 것 아닌가요?

저장의 진실 공급원은 여전히 저장소 하나입니다. 달라진 것은 입력 중인 임시 상태를 화면이 들고 있다는 점뿐이고, 이건 IME처럼 프레임 단위로 이어져야 하는 상태에 대한 정상적인 처리입니다. 아키텍처를 지키다 글자가 깨지면 지킬 이유가 없습니다.

앱 안에서 내 앱이 저장한 사진만 골라 보여 주는 갤러리 화면이 있었습니다. 잘 돌아갔습니다. 실기기에서도, 에뮬레이터에서도, 스토어에 나간 뒤에도 아무 문제가 없었습니다.

그런데 로보 테스트를 한 번 돌렸더니 이게 나왔습니다.

android.database.sqlite.SQLiteException: no such column: relative_path (code 1)
  SELECT ... FROM images WHERE (relative_path LIKE ?)
→ Force finishing activity com.example.myapp/.MainActivity

갤러리 탭을 누르는 순간 앱이 강제 종료됩니다. 조건은 하나, Android 9 이하 기기입니다.

원인 — 컬럼에도 API 레벨이 있다

MediaStore.MediaColumns.RELATIVE_PATH는 API 29(Android 10)에서 생긴 컬럼입니다. Scoped Storage가 들어오면서 절대경로 대신 쓰라고 만들어진 것입니다.

문제는 이 상수를 쓰는 코드가 구형 기기에서도 컴파일도 되고 실행도 된다는 점입니다. RELATIVE_PATH는 그냥 "relative_path"라는 문자열 상수이고, 그 문자열은 어느 API 레벨에서든 멀쩡히 존재합니다. Lint도 조용합니다.

터지는 곳은 훨씬 뒤입니다. 그 문자열이 ContentResolver.query()의 selection에 실려 미디어 DB로 넘어가고, 그 DB에 해당 컬럼이 없어서 SQLite가 예외를 던집니다. 컴파일 타임 안전장치가 하나도 걸리지 않는 종류의 API 경계입니다.

왜 아무도 못 잡았나

이 크래시는 Play Console vitals에도 Crashlytics에도 0건이었습니다. 코드가 실제로 깨져 있는데도 그랬습니다. 이유는 단순합니다.

즉 지표가 깨끗한 것은 코드가 맞다는 뜻이 아니라, 아직 아무도 그 자리를 밟지 않았다는 뜻이었습니다. 내일 Android 9 사용자가 설치하면 그대로 깨집니다. minSdk를 26으로 선언해 뒀다는 것은 그 기기에서 동작한다고 스토어에 약속했다는 의미입니다.

고친 방식 — 질의를 SDK로 가르고, 함수로 뽑는다

조회 조건을 만드는 부분을 sdkInt를 인자로 받는 순수 함수로 분리했습니다.

/** 사진이 저장되는 자리. 조회와 저장이 같은 값을 봐야 하므로 한 곳에 둔다. */
const val EVIDSNAP_DIR = "DCIM/EvidSnap"

internal fun galleryQuery(sdkInt: Int): Pair<String, Array<String>> =
    if (sdkInt >= Build.VERSION_CODES.Q) {
        "${MediaStore.Images.Media.RELATIVE_PATH} LIKE ?" to arrayOf("$EVIDSNAP_DIR/%")
    } else {
        @Suppress("DEPRECATION")
        "${MediaStore.Images.Media.DATA} LIKE ?" to arrayOf("%/$EVIDSNAP_DIR/%")
    }

호출부는 이렇게 됩니다.

val (selection, selectionArgs) = galleryQuery(Build.VERSION.SDK_INT)
contentResolver.query(
    MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
    projection, selection, selectionArgs, sortOrder
)?.use { cursor -> /* ... */ }

여기서 걸리기 쉬운 세 가지

저장 쪽도 대칭으로 갈라야 한다

읽기만 고치면 절반입니다. 저장 쪽은 이렇게 갈랐습니다.

• API 29 이상: RELATIVE_PATH + IS_PENDING을 그대로 사용
• API 28 이하: Environment.getExternalStoragePublicDirectory로 폴더를 잡고 mkdirs()로 직접 만든 뒤 MediaColumns.DATA에 절대경로를 넣습니다. 미디어스토어가 폴더를 만들어 주지 않습니다.

참고로 바로 옆의 IS_PENDING은 원래부터 >= Q로 막혀 있었고, 매니페스트에도 WRITE_EXTERNAL_STORAGE에 maxSdkVersion="28"이 붙어 있었습니다. 즉 pre-Q를 지원할 의도는 있었는데 구현만 빠진 것이었습니다. "SDK 분기를 한 군데 했으면 다 했겠지"는 근거가 안 됩니다.

경계값은 테스트로 못 박는다

sdkInt를 인자로 뺀 진짜 이유가 이것입니다. Build.VERSION.SDK_INT는 프레임워크 상수라 유닛 테스트 런타임에서 바꿀 수 없습니다. 인자로 받으면 경계 양쪽을 그냥 호출해서 확인할 수 있습니다.

@Test
fun `pre-Q 는 DATA 절대경로로 조회한다`() {
    val (selection, args) = galleryQuery(28)
    assertTrue(selection.startsWith("_data"))
    assertTrue(args[0].startsWith("%/"))   // 절대경로라 앞에 % 가 있어야 한다
}

@Test
fun `Q 이상은 RELATIVE_PATH 로 조회한다`() {
    val (selection, _) = galleryQuery(29)
    assertTrue(selection.startsWith("relative_path"))
}

28과 29를 둘 다 확인하는 게 요점입니다. 한쪽만 두면 경계가 어디인지를 검증하지 못합니다.

덧 — 테스트는 이걸 왜 못 잡았나

같은 앱의 계측 테스트가 갤러리 화면을 열고 있었는데도 이 크래시를 못 잡았습니다. 나중에 보니 그 테스트 자신이 minSdk에서 안 돌고 있었습니다. 권한 @Rule에 API 33+ 전용 권한 이름을 못박아 둬서, 그 미만 기기에서는 본문이 시작조차 못 하고 있었습니다.

같은 계열의 다른 사고라 따로 정리해 두었습니다 — (계측 테스트가 minSdk에서 안 돌고 있었다 편). 이 글이 "앱이 왜 죽었나"라면, 그쪽은 "검증이 왜 초록불이었나"입니다.

정리

• RELATIVE_PATH는 API 29부터입니다. 문자열 상수라 컴파일·Lint가 안 잡아 줍니다.
• 조회는 죽고, 저장은 조용히 어긋납니다. 둘 다 갈라야 합니다.
• 실사용자 분포가 크래시를 가려 줍니다. 지표 0건은 안전의 근거가 아닙니다.
• SDK 분기는 인자 받는 함수로 뽑아 경계 양쪽을 테스트로 고정하세요.

자주 묻는 것

minSdk를 29로 올려 버리면 안 되나요?

가능한 선택이고, 그 편이 코드는 훨씬 단순해집니다. 다만 그건 버리는 사용자층을 알고 내리는 결정이어야 합니다. 26으로 두고 구현을 안 하는 것이 문제였지, 26 자체가 문제는 아닙니다.

Android 9 에뮬레이터에서도 사진이 안 보이는데요?

저장 쪽 분기를 안 고쳤다면 사진이 다른 폴더에 떨어져 있습니다. 조회를 고쳐도 없는 곳을 찾는 셈이라 계속 비어 보입니다. 저장 분기의 mkdirs()까지 확인하세요.

DATA를 쓰면 정책 위반 아닌가요?

deprecated는 "쓰지 말라"가 아니라 "새 코드에서는 다른 것을 쓰라"입니다. API 28 이하 분기 안에서만 쓰는 것이라 Scoped Storage 정책과 충돌하지 않습니다. 29 이상에서 쓰지 않도록 분기를 확실히 갈라 두는 게 중요합니다.

위젯을 붙인 앱에서 Crashlytics에 이런 것이 올라옵니다.

FATAL EXCEPTION: main
java.lang.RuntimeException: Unable to start activity
    ComponentInfo{...androidx.glance.appwidget.action.InvisibleActionTrampolineActivity}
Caused by: java.lang.IllegalArgumentException:
    List adapter activity trampoline invoked without specifying target intent.
    at androidx.glance.appwidget.action.ActionTrampolineKt
        .launchTrampolineAction(ActionTrampoline.kt:93)

내 폰에서 위젯을 아무리 눌러도 재현되지 않습니다. 에뮬레이터에서도 멀쩡합니다. 그런데 사용자에게는 계속 납니다. 스택 트레이스에 내가 쓴 코드가 한 줄도 없어서 어디서부터 봐야 할지도 막막합니다.

제 앱에서는 이걸 두 번 겪었습니다. 한 번은 원인을 찾아 막았는데, 8일 뒤 같은 예외가 그대로 다시 났습니다. 막아야 할 컴포넌트가 하나가 아니었기 때문입니다.

이 액티비티는 내가 만든 게 아니다

InvisibleActionTrampolineActivity는 androidx.glance:glance-appwidget이 자기 매니페스트에 선언해 넣는 컴포넌트입니다. 매니페스트 병합 결과물에는 들어 있지만 내 프로젝트 소스 어디를 뒤져도 나오지 않습니다.

하는 일은 이름 그대로 중계(트램폴린)입니다. 시작할 때 받은 인텐트에서 목적지 인텐트를 꺼내 그쪽으로 넘기고 자신은 사라집니다. 문제는 그 목적지 정보가 없을 때입니다. 그러면 위 IllegalArgumentException을 던지고, 액티비티 시작 중 발생한 예외라 앱이 그대로 죽습니다.

핵심 — 트램폴린은 두 개다

여기가 제가 8일을 날린 지점입니다. glance-appwidget 1.1.1은 이름이 비슷한 트램폴린 액티비티를 두 개 넣습니다.

저는 처음에 로그에 찍힌 Invisible 쪽만 끄고 배포했습니다. 그리고 8일 뒤, 형제 쪽으로 FATAL 5건이 사용자 4명에게 났습니다. Crashlytics에서는 예외 메시지도 발생 줄 번호도 같아서, 처음에는 수정이 반영이 안 된 줄 알았습니다. 컴포넌트 이름을 대조하고서야 절반만 막혀 있었다는 걸 알았습니다.

해결 — 매니페스트에서 둘 다 끈다

<application> 안에 두 블록을 나란히 넣습니다.

<activity
    android:name="androidx.glance.appwidget.action.InvisibleActionTrampolineActivity"
    android:enabled="false"
    tools:node="merge"
    tools:replace="android:enabled" />

<activity
    android:name="androidx.glance.appwidget.action.ActionTrampolineActivity"
    android:enabled="false"
    tools:node="merge"
    tools:replace="android:enabled" />

<manifest> 태그에 tools 네임스페이스가 없으면 같이 넣어야 합니다.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

속성 두 개가 왜 필요한가

꺼도 되는 근거 — 정상 클릭은 이 경로를 안 탄다

남의 라이브러리 컴포넌트를 끄는 것이라, 무엇을 잃는지 확인하고 넣어야 합니다. glance-appwidget 1.1.1 기준으로 확인한 내용입니다.

• 트램폴린 인텐트를 심는 applyTrampolineIntent는 getFillInIntentForAction 안에서만 호출됩니다. 이 함수는 Lazy 컬렉션 경로(LazyColumn 등의 항목 클릭)에서 쓰입니다.
• actionRunCallback은 브로드캐스트로 갑니다.
• actionStartActivity는 PendingIntent.getActivity로 갑니다.

즉 위젯에 Lazy 컬렉션이 없다면 일반 버튼과 클릭은 이 액티비티를 거치지 않고, 꺼도 동작이 달라지지 않습니다. 제 위젯 세 개가 그 조건이라 껐고, 끈 뒤 위젯 클릭은 그대로 동작합니다.

막혔는지 확인하는 법

배포 전에 직접 찔러 볼 수 있습니다. 다만 일반 셸에서는 확인이 안 됩니다. 이 액티비티들은 exported="false"라, 셸 사용자(uid 2000)로 실행하면 컴포넌트가 켜져 있든 꺼져 있든 SecurityException이 먼저 뜹니다.

그래서 루팅된 에뮬레이터에서 확인합니다.

adb root
adb shell am start -n com.example.myapp/androidx.glance.appwidget.action.InvisibleActionTrampolineActivity

저는 이 방법으로 수정 전 상태에서 크래시를 한 건 재현한 뒤 블록을 넣었습니다. 재현을 못 해 본 채로 "이걸 끄면 아마 될 것"으로 배포하는 것과는 확신의 크기가 다릅니다. 컴포넌트 이름만 바꿔서 형제 쪽도 같이 확인하세요.

정직하게 남겨 둘 것 — 무엇이 이걸 시작하는지는 모른다

글을 이렇게 끝내고 싶지만, 확인 못 한 부분을 확인한 것처럼 쓰면 다음에 이걸 읽는 사람이 저처럼 헛다리를 짚습니다.

어떤 주체가 이 트램폴린을 목적지 인텐트 없이 시작하는지는 끝내 특정하지 못했습니다. 저는 스토어 업로드마다 도는 자동 검사가 am start로 컴포넌트를 훑는 것이라 짐작했는데, 실기기에서 재 보니 셸은 exported="false"에 막혀 SecurityException을 받습니다. 그 경로가 아니라는 것만 확인된 셈입니다.

그래도 막는 이유는, 정상 동작에서는 어차피 안 불리는 경로라 끄는 쪽의 손해가 없기 때문입니다. 원인 경로를 안다고 가정하고 하나만 껐던 것이 애초의 실수였습니다.

정리

• 스택에 내 코드가 없는 크래시라도 매니페스트 병합 결과물에는 범인이 있을 수 있습니다.
• Glance를 쓰면 InvisibleActionTrampolineActivity와 ActionTrampolineActivity 둘 다 끕니다.
• 끌 때는 tools:node="merge" + tools:replace="android:enabled"를 같이 씁니다.
• 위젯에 Lazy 컬렉션이 없을 때만 안전합니다. 넣게 되면 그때 걷어내세요.

자주 묻는 것

Crashlytics에 안 잡히는데 괜찮은 건가요?

위젯을 쓰는 앱이고 Glance 버전이 같다면 소지는 있습니다. 저는 한 앱에서 사용자 2명이 겪은 걸 보고 같은 구조의 다른 앱에도 선제로 넣었습니다. 지표가 깨끗한 것과 코드가 맞는 것은 다릅니다.

Glance를 올리면 해결되나요?

제가 확인한 건 1.1.1 기준입니다. 상위 버전에서 동작이 바뀌었는지는 검증하지 않았으니, 올린다면 위 adb root 확인을 다시 해 보고 판단하세요.

액티비티를 지우면(tools:node="remove") 안 되나요?

enabled="false"는 선언은 남기고 시작만 막는 쪽이라 라이브러리 다른 코드가 이 컴포넌트를 참조해도 병합이 깨지지 않습니다. 저는 remove는 시도하지 않았습니다.

윈도우에서 클로드 코드(Claude Code)를 쓰다 보면 한글이 세 군데에서 각각 다르게 깨집니다.

// ① 터미널 출력
?????? ??? ???

// ② 파이썬 실행
UnicodeEncodeError: 'cp949' codec can't encode character '✓'

// ③ 만들어 준 PowerShell 스크립트 실행
+ Write-Output "?��?��"
              ~~~~~~
문자열에 종료 기호가 없습니다.

세 증상 모두 AI 도구의 버그가 아닙니다. 윈도우의 기본 문자 인코딩이 UTF-8이 아니라 CP949(euc-kr 계열)이기 때문에 생기는 오래된 문제이고, 도구가 한글을 많이 다루게 되면서 한꺼번에 드러난 것입니다.

깨지는 지점이 셋이므로, 고치는 곳도 셋입니다. 하나만 고치고 "왜 아직도 깨지지"를 반복하는 경우가 대부분입니다.

① 터미널 출력이 ?로 나올 때

콘솔의 코드페이지를 UTF-8(65001)로 바꿉니다. 임시로는 이 한 줄이면 됩니다.

chcp 65001

PowerShell이라면 출력·입력 인코딩까지 함께 지정하는 편이 확실합니다.

# PowerShell 프로필에 넣어두면 매번 적용된다
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding  = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

프로필 파일 위치는 이렇게 확인하고, 없으면 만들면 됩니다.

echo $PROFILE
# 없으면
New-Item -ItemType File -Path $PROFILE -Force

근본 해결 — 시스템 로캘을 UTF-8로

매번 설정하기 싫다면 윈도우 전체를 UTF-8로 돌릴 수 있습니다.

설정 → 시간 및 언어 → 언어 및 지역 → 시스템 로캘 변경 → "세계 언어 지원을 위한 Beta: 유니코드 UTF-8 사용" 체크 → 재부팅

② UnicodeEncodeError: 'cp949' — 파이썬

파이썬이 print()로 한글이나 특수문자(✓, →, 이모지)를 출력할 때 터집니다. 스크립트 안의 한글은 멀쩡한데 출력하는 순간 죽는 것이 특징입니다.

방법 A — 환경 변수 (가장 간단)

# 현재 세션만
$env:PYTHONIOENCODING = "utf-8"

# 영구 적용
[Environment]::SetEnvironmentVariable(
    "PYTHONIOENCODING", "utf-8", "User")

방법 B — 스크립트 자체가 스스로 해결하게 (권장)

다른 PC나 자동화(작업 스케줄러)에서도 돌아가야 한다면, 환경 변수에 기대지 말고 스크립트 상단에서 표준 출력을 UTF-8로 다시 감싸는 편이 안전합니다.

# -*- coding: utf-8 -*-
import sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")

파일 읽기·쓰기도 마찬가지

# ❌ 윈도우에서는 기본이 cp949 라 깨진다
open("data.txt").read()

# ✅ 항상 명시
open("data.txt", encoding="utf-8").read()
open("out.txt", "w", encoding="utf-8").write(text)

③ 스크립트가 실행조차 안 될 때 — BOM 문제

여기가 가장 안 알려져 있고, 가장 오래 헤매는 지점입니다. AI가 만들어 준 .ps1 파일을 실행했더니 문법 오류가 나고, 열어보면 코드는 멀쩡합니다.

Write-Output "발행 완료"
# → 문자열에 종료 기호가 없습니다.

Windows PowerShell 5.1은 BOM이 없는 파일을 CP949로 읽습니다. UTF-8로 저장된 한글이 CP949로 해석되면서 따옴표 짝이 깨진 것처럼 보이는 것입니다. 코드가 아니라 파일이 저장된 방식이 문제입니다.

# BOM 포함으로 다시 저장
$content = Get-Content .\script.ps1 -Raw -Encoding UTF8
[System.IO.File]::WriteAllText(
    "$PWD\script.ps1", $content,
    [System.Text.UTF8Encoding]::new($true))   # $true = BOM 포함

에디터에서라면 VS Code 오른쪽 아래 인코딩 표시를 눌러 Save with Encoding → UTF-8 with BOM을 고르면 됩니다.

Set-Content로 파일을 만들 때

# ❌ PowerShell 5.1의 Set-Content 기본값은 시스템 ANSI(CP949)
Set-Content out.txt $text

# ✅ 명시
Set-Content out.txt $text -Encoding utf8

AI 도구에 아예 규칙으로 박아두기

매번 "한글 안 깨지게 저장해 줘"라고 말하는 대신, 프로젝트 규칙 파일(CLAUDE.md 등)에 적어두면 계속 적용됩니다. 실제로 효과가 큰 부분입니다.

# 인코딩 규칙 (윈도우 환경)

- 모든 텍스트 파일은 UTF-8 로 저장한다.
- .ps1 파일은 반드시 UTF-8 **BOM 포함** 으로 저장한다.
  (BOM 이 없으면 PowerShell 5.1 이 CP949 로 읽어 파싱이 깨진다)
- 파이썬 스크립트는 상단에 표준 출력 UTF-8 래핑을 넣는다.
- open() 과 Set-Content 에는 인코딩을 항상 명시한다.

터미널에서 한글 입력이 이상할 때

출력이 아니라 입력 쪽 증상도 있습니다. 한글을 치는 도중 글자가 커서와 어긋나게 그려지거나, 문장 중간을 수정하면 조합이 흐트러지는 현상입니다.

이것은 코드페이지가 아니라 터미널의 IME 처리 문제라 설정으로 해결되지 않습니다. 대응은 두 가지입니다.

• 도구를 최신 버전으로 업데이트 — 한국어·중국어·일본어 조합 입력 처리는 개선이 이어지는 영역입니다.
• 긴 한글 프롬프트는 다른 곳에서 작성해 붙여넣기 — 조합 중 렌더링 문제라, 완성된 문자열을 붙여넣으면 영향을 받지 않습니다.

점검 순서

자주 묻는 질문

Q. chcp 65001을 했는데도 깨집니다.

깨지는 지점이 출력이 아니라 파일 저장일 가능성이 큽니다. 그 파일을 VS Code로 열어 오른쪽 아래 인코딩 표시를 확인하세요. CP949로 저장돼 있다면 코드페이지를 아무리 바꿔도 그대로입니다.

Q. 손으로 실행하면 되는데 작업 스케줄러에서만 깨집니다.

실행 계정이 달라 환경 변수가 적용되지 않은 것입니다. 환경 변수 대신 스크립트 자체가 인코딩을 지정하도록 바꾸면 실행 주체와 무관해집니다.

Q. UTF-8 BOM을 넣으면 다른 데서 문제 되지 않나요?

.ps1은 BOM이 있어야 안전하고, 반대로 셸 스크립트(.sh)·JSON·YAML은 BOM이 있으면 안 됩니다. 파일 종류에 따라 다르므로 일괄로 BOM을 붙이지 마세요.

Q. PowerShell 7을 쓰면 해결되나요?

많이 나아집니다. 기본 인코딩이 UTF-8이라 BOM 문제에서 자유롭습니다. 다만 윈도우에 기본 설치된 5.1도 함께 남아 있으므로, 스크립트가 어느 쪽으로 실행되는지는 여전히 확인해야 합니다.

Q. AI가 만든 코드의 한글 주석만 깨집니다.

파일 저장 인코딩 문제입니다. 소스 파일을 UTF-8로 저장하고, 자바 계열이라면 컴파일 옵션에 -encoding UTF-8이 들어가 있는지도 확인하세요.

정리

윈도우에서 한글이 깨질 때 가장 먼저 할 일은 고치는 게 아니라 어디서 깨졌는지 가르는 것입니다. 화면에서 깨진 것인지, 파일에 잘못 저장된 것인지, 파일은 멀쩡한데 읽는 쪽이 잘못 해석한 것인지에 따라 답이 완전히 다릅니다.

그리고 한 번 고쳤으면 규칙으로 남기세요. 인코딩 문제는 잊을 만하면 다른 얼굴로 돌아오고, 그때마다 같은 시간을 다시 씁니다.

앱 안 웹뷰에서 "구글로 로그인"을 눌렀더니 로그인 화면 대신 이 문구가 뜹니다.

403. That's an error.

Error: disallowed_useragent

You can't sign in from this screen because
this app doesn't comply with Google's secure browsers policy.

모바일 크롬에서 같은 페이지를 열면 잘 됩니다. 앱 안에서만 막힙니다. 카카오·네이버 로그인은 되는데 구글만 안 되는 것도 흔한 조합입니다.

원인 — 구글이 내장 웹뷰의 로그인을 정책으로 막았다

버그가 아니라 의도된 차단입니다. 구글은 2021년 9월 말부터 앱에 내장된 웹뷰(embedded WebView)에서의 OAuth 인증을 허용하지 않습니다. 이유는 보안입니다.

웹뷰는 앱이 그 안을 들여다볼 수 있습니다. 자바스크립트를 주입해 입력값을 읽거나, 화면을 캡처하거나, 쿠키를 꺼낼 수 있습니다. 즉 악의적인 앱이 진짜 구글 로그인 화면을 띄워놓고 아이디와 비밀번호를 그대로 가져갈 수 있다는 뜻입니다. 사용자는 주소창이 없어서 진짜인지 확인할 방법도 없습니다.

먼저 — 하면 안 되는 우회 두 가지

정답은 하나입니다. 로그인 구간만 웹뷰 밖으로 꺼내는 것입니다.

해결 — 로그인만 Custom Tabs로 연다

Chrome Custom Tabs는 앱 안에 떠 있는 진짜 브라우저입니다. 앱은 그 안을 볼 수 없고, 사용자는 주소창으로 도메인을 확인할 수 있으며, 크롬에 로그인돼 있으면 계정 선택만으로 끝납니다. 구글이 요구하는 조건을 모두 만족합니다.

1단계 — 의존성

// build.gradle.kts
implementation("androidx.browser:browser:1.8.0")

2단계 — 로그인 URL만 가로채서 Custom Tabs로 넘긴다

웹뷰는 그대로 두고, 구글 인증 주소로 이동하려는 순간에만 끼어들면 됩니다.

webView.webViewClient = object : WebViewClient() {

    override fun shouldOverrideUrlLoading(
        view: WebView, request: WebResourceRequest
    ): Boolean {
        val url = request.url.toString()

        if (isOAuthUrl(url)) {
            openInCustomTab(view.context, url)
            return true          // 웹뷰는 열지 않는다
        }
        return false
    }

    private fun isOAuthUrl(url: String): Boolean =
        url.startsWith("https://accounts.google.com/") ||
        url.startsWith("https://appleid.apple.com/auth/authorize")
}

private fun openInCustomTab(context: Context, url: String) {
    CustomTabsIntent.Builder()
        .setShowTitle(true)
        .build()
        .launchUrl(context, Uri.parse(url))
}

3단계 — 로그인 끝나고 앱으로 돌아오게 만든다

여기서 대부분 막힙니다. Custom Tabs로 로그인은 됐는데 브라우저에 머물러 있고 앱으로 안 돌아옵니다. 인증이 끝난 뒤 서버가 보내는 리다이렉트 주소를 앱이 받을 수 있는 주소로 만들어야 합니다.

<!-- AndroidManifest.xml -->
<activity
    android:name=".AuthCallbackActivity"
    android:exported="true"
    android:launchMode="singleTask">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <!-- 서버가 최종적으로 리다이렉트할 주소 -->
        <data android:scheme="myapp" android:host="auth" />
    </intent-filter>
</activity>

class AuthCallbackActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // myapp://auth?token=... 형태로 돌아온다
        val token = intent?.data?.getQueryParameter("token")

        if (token != null) {
            // 세션 저장 후 원래 화면으로 복귀
            SessionStore.save(token)
            startActivity(Intent(this, MainActivity::class.java).apply {
                flags = Intent.FLAG_ACTIVITY_CLEAR_TOP
            })
        }
        finish()
    }
}

4단계 — 돌아온 세션을 웹뷰가 알게 한다

Custom Tabs와 웹뷰는 쿠키 저장소가 다릅니다. 브라우저에서 로그인했다고 웹뷰가 로그인 상태가 되지는 않습니다. 그래서 돌려받은 토큰을 웹뷰 쪽에 심어줘야 합니다.

// 토큰을 쿼리로 넘겨 서버가 웹뷰 세션을 만들게 하거나
webView.loadUrl("https://example.com/app/enter?token=$token")

// 서버가 쿠키 기반이라면 직접 주입
CookieManager.getInstance().apply {
    setAcceptCookie(true)
    setCookie("https://example.com", "session=$token; Path=/; Secure; HttpOnly")
    flush()          // ★ 빼먹으면 앱 재시작 시 로그인이 풀린다
}

다른 선택지 — 아예 네이티브 로그인으로

웹뷰 껍데기 앱이 아니라 네이티브 화면이 있는 앱이라면, 웹 OAuth 대신 안드로이드 네이티브 로그인을 쓰는 편이 사용자 경험이 훨씬 낫습니다. 계정 선택 시트가 바로 뜨고 브라우저를 거치지 않습니다.

점검 순서

자주 묻는 질문

Q. User-Agent를 바꿨더니 되던데요?

지금은 통과할 수 있습니다. 문제는 그것이 정책 위반이라 언제든 다시 막힌다는 점입니다. 그때는 이미 출시된 앱의 로그인이 통째로 죽고, 스토어 업데이트가 반영될 때까지 사용자는 들어오지 못합니다. 실제로 이 방식으로 버티다 한 번에 무너지는 사례가 반복돼 왔습니다.

Q. 카카오·네이버 로그인은 웹뷰에서 잘 되는데요?

각 서비스의 정책이 다릅니다. 다만 국내 서비스들도 자체 SDK나 앱 전환 방식을 권장하는 방향으로 가고 있습니다. 구글만 예외적으로 엄격한 것이지, 웹뷰 안에서 남의 계정 로그인을 처리하는 구조 자체가 권장되지 않습니다.

Q. Custom Tabs를 열었더니 브라우저 앱으로 완전히 튀어나갑니다.

CustomTabsIntent가 아니라 일반 ACTION_VIEW 인텐트로 열고 있을 가능성이 큽니다. 또는 기기에 Custom Tabs를 지원하는 브라우저가 없어 폴백된 경우입니다. 후자는 정상 동작이며, 앱 복귀는 앱 스킴 콜백이 처리합니다.

Q. 로그인은 되는데 앱으로 안 돌아옵니다.

3단계의 앱 스킴 설정 문제입니다. BROWSABLE 카테고리 누락, 스킴 오타, 서버가 보내는 최종 리다이렉트 주소 불일치 중 하나입니다. 브라우저 주소창에 myapp://auth를 직접 쳐서 앱이 뜨는지부터 확인하면 빠릅니다.

Q. 앱을 껐다 켜면 로그인이 풀립니다.

쿠키를 주입한 뒤 CookieManager.flush()를 호출하지 않아서입니다. 웹뷰 쿠키는 메모리에 있다가 flush 시점에 디스크로 내려갑니다.

정리

disallowed_useragent는 고칠 수 있는 오류가 아니라 지켜야 할 규칙입니다. 앱이 들여다볼 수 있는 화면에서는 남의 계정 로그인을 받지 말라는 것이고, 그 요구는 앞으로 더 강해질 방향이지 느슨해질 방향이 아닙니다.

따라서 로그인 구간만 Custom Tabs로 꺼내고, 인증이 끝나면 앱 스킴으로 돌아와 세션을 웹뷰에 심는 것이 정공법입니다. 작업량은 반나절이면 충분하고, User-Agent를 바꾸며 버티는 방식보다 훨씬 오래갑니다.

앱 안 웹뷰가 흰 화면이거나 회색 오류 페이지를 띄우고, 로그캣에 이렇게 찍힙니다.

net::ERR_CACHE_MISS

같은 주소를 모바일 크롬으로 열면 멀쩡합니다. 검색하면 "인터넷 권한을 추가하세요"라는 답이 가장 먼저 나오는데, 권한이 이미 있는데도 나는 경우가 절반은 됩니다. 이름 그대로 "캐시에서 못 찾았다"는 뜻이라 원인이 세 갈래로 갈리기 때문입니다.

먼저 세 갈래 중 어디인지 가른다

이 구분을 먼저 하지 않고 코드를 고치면, 남의 답을 그대로 붙여넣어 놓고 "왜 안 되지"를 반복하게 됩니다.

원인 ① INTERNET 권한 — 가장 흔하고 가장 허무하다

웹뷰는 네트워크를 못 쓰면 캐시에서 찾으려 하고, 캐시도 없으니 ERR_CACHE_MISS를 냅니다. "인터넷이 없다"가 아니라 "캐시에 없다"로 나오는 탓에 원인이 잘 안 보입니다.

<!-- AndroidManifest.xml — <application> 바깥, 최상위에 -->
<uses-permission android:name="android.permission.INTERNET" />

원인 ② 캐시 모드 — LOAD_CACHE_ONLY가 범인

웹뷰의 캐시 정책은 네 가지입니다. 이 중 하나를 잘못 고르면 네트워크가 멀쩡해도 오류가 납니다.

오프라인 대응을 넣다가 LOAD_CACHE_ONLY로 고정해 둔 코드가 대표적인 사고 지점입니다. 캐시가 비어 있는 첫 실행에서 100% 실패합니다.

webView.settings.apply {
    javaScriptEnabled = true
    domStorageEnabled = true
    cacheMode = WebSettings.LOAD_DEFAULT   // ★ 특별한 이유 없으면 이것
}

네트워크 상태에 따라 갈라야 한다면, 고정하지 말고 그때그때 판단해야 합니다.

private fun currentCacheMode(context: Context): Int {
    val cm = context.getSystemService(ConnectivityManager::class.java)
    val caps = cm.getNetworkCapabilities(cm.activeNetwork)
    val online = caps?.hasCapability(
        NetworkCapabilities.NET_CAPABILITY_INTERNET) == true

    return if (online) WebSettings.LOAD_DEFAULT
           else WebSettings.LOAD_CACHE_ELSE_NETWORK
}

// 로드 직전에 적용
webView.settings.cacheMode = currentCacheMode(this)
webView.loadUrl(url)

같이 볼 것 — 네트워크 로드 차단 플래그

setBlockNetworkLoads(true)를 켜 두면 캐시 모드와 무관하게 통신이 막혀 같은 오류가 납니다. 오프라인 진입 시 켜고 복귀할 때 끄는 것을 빼먹은 코드가 흔합니다.

webView.settings.blockNetworkLoads = false   // 온라인 복귀 시 반드시 해제
// blockNetworkImage 도 같은 방식으로 관리

원인 ③ POST 뒤로가기 — 캐시가 없는 게 정상인 경우

로그인·검색·주문처럼 POST로 이동한 페이지는 웹뷰가 캐시에 담지 않습니다. 그래서 뒤로가기나 새로고침으로 그 페이지를 다시 그리려 하면 가져올 캐시가 없어서 ERR_CACHE_MISS가 납니다. 이 경우는 설정 실수가 아니라 구조의 문제입니다.

세 가지 대응이 있고, 상황에 따라 고르면 됩니다.

대응 A — 서버가 POST 뒤에 리다이렉트하게 한다 (권장)

POST 처리 후 결과 페이지로 302 리다이렉트하면(PRG 패턴), 히스토리에 남는 것은 GET이라 뒤로가기가 깨지지 않습니다. 웹 쪽을 고칠 수 있다면 이게 가장 깔끔합니다.

대응 B — 뒤로가기를 앱이 직접 처리한다

// 히스토리 항목이 POST였다면 뒤로가기 대신 새로 로드
webView.setOnKeyListener { _, keyCode, event ->
    if (keyCode == KeyEvent.KEYCODE_BACK && event.action == KeyEvent.ACTION_UP) {
        if (webView.canGoBack()) {
            webView.goBack()
        } else {
            finish()
        }
        true
    } else false
}

그래도 깨지는 화면이 있다면, 해당 URL만 기억해 두었다가 GET으로 다시 로드하는 편이 확실합니다.

대응 C — 오류를 잡아 한 번 재시도

사용자에게 회색 오류 페이지를 보여주지 않기 위한 안전망입니다.

webView.webViewClient = object : WebViewClient() {

    private var retried = false

    override fun onReceivedError(
        view: WebView, request: WebResourceRequest, error: WebResourceError
    ) {
        // 메인 프레임의 캐시 미스만 재시도 (이미지·광고 실패는 무시)
        if (!request.isForMainFrame) return
        if (error.errorCode != ERROR_UNKNOWN &&
            error.description?.contains("CACHE_MISS") != true) return

        if (!retried) {
            retried = true
            view.settings.cacheMode = WebSettings.LOAD_NO_CACHE
            view.loadUrl(request.url.toString())
        }
    }
}

"매번 LOAD_NO_CACHE로 하면 되지 않나요"

증상은 사라집니다. 대신 모든 요청이 네트워크로 나갑니다. 이미지와 CSS까지 매번 다시 받으므로 화면 전환이 눈에 띄게 느려지고 데이터도 더 씁니다. 원인 ①·③이 진짜 이유였다면, 문제를 덮은 채 성능만 잃는 선택입니다.

임시 확인용으로는 유용합니다. LOAD_NO_CACHE로 바꿨을 때 바로 해결되면 원인 ②, 그래도 안 되면 원인 ①일 가능성이 큽니다. 진단 도구로 쓰고 되돌리세요.

Flutter · React Native일 때

점검 순서

자주 묻는 질문

Q. 권한도 있고 캐시 모드도 기본값인데 계속 납니다.

실패하는 시점을 보세요. 버튼을 누른 직후나 뒤로가기에서만 난다면 POST 히스토리 문제라 설정으로는 안 풀립니다. 서버 쪽 리다이렉트(PRG) 또는 앱에서의 재로드로 접근해야 합니다.

Q. 크롬에서는 되는데 웹뷰에서만 납니다.

정상입니다. 크롬은 자체 캐시와 네트워크 스택 설정을 쓰고, 웹뷰는 앱이 지정한 설정을 씁니다. 비교 대상이 아니라 서버가 살아 있다는 확인용으로만 쓰세요.

Q. 에뮬레이터에서만 납니다.

에뮬레이터의 네트워크가 끊겨 있거나 프록시 설정이 남아 있는 경우가 많습니다. 브라우저 앱으로 아무 사이트나 열어 네트워크 자체를 먼저 확인하세요.

Q. 재시도 코드를 넣었더니 화면이 계속 깜빡입니다.

재시도 플래그가 없어 무한 루프에 빠진 것입니다. 한 번만 재시도하도록 막고, 성공 시(onPageFinished) 플래그를 초기화하세요.

정리

ERR_CACHE_MISS는 "캐시에서 못 찾았고, 네트워크로도 못 갔다"는 신호입니다. 그래서 답이 하나가 아닙니다. 권한이 없어서 네트워크로 못 간 것인지, 캐시 모드가 네트워크를 막은 것인지, 애초에 캐시가 있을 수 없는 POST 페이지인지를 먼저 가르는 것이 해결의 전부입니다.

가장 빠른 진단은 앱 데이터를 지우고 첫 실행에서 재현해 보는 것입니다. 그때 모든 페이지가 실패하면 권한, 특정 화면만 실패하면 캐시 모드, 버튼을 누른 뒤에만 실패하면 POST입니다.