[해결] 안드로이드 구글맵이 빈 화면으로 나올 때 — 마커는 보이는데 지도만 안 뜨는 이유

러닝 앱을 실제로 밖에서 테스트하던 날이었어요. 달리기를 시작하고 폰을 봤더니 지도가 베이지색 빈 화면으로 나오더라고요.

이상한 건 경로선은 멀쩡히 그려지고 있었다는 거예요. 내 위치 마커도 움직이고, 왼쪽 아래 "Google" 로고도 떠 있었어요. 도로랑 건물만 하나도 안 보였고요.

처음엔 GPS나 네트워크 문제인 줄 알았어요. 그런데 원인은 전혀 다른 데 있었어요. 같은 증상으로 검색하다 들어오신 분이 많을 것 같아서 정리해둡니다.

마커는 보이는데 지도만 안 보인다면

이 증상에서 제일 중요한 단서는 "무엇은 보이고 무엇은 안 보이느냐"예요.

경로선, 마커, Google 로고는 지도 SDK가 직접 그리는 것들이에요. 이게 보인다는 건 SDK도, 앱 코드도, 화면 렌더링도 정상이라는 뜻이에요.

안 보이는 건 지도 타일, 그러니까 도로와 건물이 그려진 이미지 조각이에요. 이건 구글 서버에서 받아와야 하는데, 이걸 받아오는 단계에서 막힌 거예요.

지도에서 보이는 것과 안 보이는 것으로 원인 가르기

그래서 이 증상이면 코드부터 뒤질 필요가 없어요. 위치 권한, GPS, SHA-1 인증서 지문 같은 것도 대부분 상관없고요. 십중팔구 API 키, 결제 계정, API 사용 설정 셋 중 하나예요.

키를 직접 던져보면 원인이 바로 나와요

콘솔을 이리저리 눌러보는 것보다 빠른 방법이 있어요. 앱에 넣은 그 API 키로 구글 지도 API를 터미널에서 직접 호출해보는 거예요.

KEY="앱에 넣은 API 키"
curl -s "https://maps.googleapis.com/maps/api/geocode/json?address=Seoul&key=$KEY"

응답에 error_message가 같이 오는데, 이 문구가 원인을 그대로 말해줘요.

curl 응답의 error_message별 원인과 조치

하나만 주의할 게 있어요. Geocoding API는 안드로이드 지도 SDK(Maps SDK for Android)와 별개 API라서, 안 켜뒀다면 "not activated"가 나오는 게 정상이에요. 그 문구만 보고 놀랄 필요는 없어요.

진짜 신호는 "The provided API key is invalid."예요. 이게 나오면 키 자체가 죽은 거예요. 콘솔에서 키를 지우고 다시 만들었거나, 프로젝트에 옛날 키가 남아 있는 경우죠.

또 키에 "Android 앱만 허용" 제한을 걸어두셨다면 curl은 앱 정보가 없어서 거부될 수 있어요. 이때는 이 방법으로는 확인이 안 되니 실제 앱 빌드로 확인하셔야 해요.

"어제는 됐는데요?" 의 정체

이 문제가 헷갈리는 이유가 하나 더 있어요. 캐시된 타일이에요.

예전에 한 번 본 지역은 폰에 타일이 남아 있어서 키가 죽어도 지도가 떠요. 개발하면서 늘 보던 위치는 멀쩡하니까 "어제까지 됐는데?" 싶은 거죠.

그러다 처음 가는 곳에서 열면 그제야 빈 화면이 나와요. 저도 책상 앞에선 멀쩡하다가 밖에서 달리면서 처음 알았어요. 지도가 됐다 안 됐다 한다면 캐시와 키 문제를 같이 의심해보세요.

해결 순서

구글맵 빈 화면 해결 순서

순서대로 정리하면 이래요.

1. curl로 원인부터 확정합니다. 위 명령으로 1분이면 돼요.
2. 키가 죽었으면 새로 발급합니다. Google Cloud 콘솔 → API 및 서비스 → 사용자 인증 정보에서 만들 수 있어요.
3. Maps SDK for Android 사용 설정과 결제 계정 연결을 확인합니다. 둘 중 하나만 빠져도 타일이 안 와요.
4. 새 키로 바꾸고 다시 빌드합니다. 보통 local.properties에 넣고 매니페스트로 주입하는 구조라, 파일만 바꾸고 빌드를 안 하면 예전 키가 그대로 들어가요.
5. 처음 가보는 지역으로 확인합니다. 늘 보던 위치는 캐시 때문에 확인이 안 돼요.

APK에 새 키가 실제로 들어갔는지 확인하고 싶으면 이 명령도 쓸 만해요.

aapt dump xmltree app-debug.apk AndroidManifest.xml | grep -A1 geo.API_KEY

정리하면

지도가 빈 화면인데 마커와 로고가 보인다면, 코드가 아니라 키와 콘솔 설정 문제일 가능성이 높아요. curl 한 줄로 원인을 확인하고, 처음 가보는 지역으로 결과를 확인하면 헛걸음을 많이 줄일 수 있어요.

참고로 이 문제를 겪은 앱은 제가 만든 러닝 앱 런피커예요. 달리는 동안 음성으로 페이스를 코칭해 주고, 달린 경로를 지도에 그려줘요. 이번 일 이후로 지도는 처음 가는 곳에서도 확인하고 있어요 ^^

▶ 런피커 플레이 스토어에서 보기