문제 해결

이 플러그인의 설치 단계와 전체 마크다운 가이드가 포함된 설정 프롬프트를 복사하세요.

Capgo Cloud Build로 Native Build 시 발생하는 일반적인 문제 해결 방법입니다.

빌드 실패

“업로드 실패” 또는 “연결 타임아웃”

증상:

프로젝트 업로드 중 빌드 실패
60초 후 타임아웃 오류 발생

해결 방법:

인터넷 연결 상태 확인

# Test connection to Capgo
curl -I https://api.capgo.app

프로젝트 크기 줄이기
- 확인하세요 node_modules/ 업로드되지 않음 (자동 제외되어야 함)
- 프로젝트에 대용량 파일이 있는지 확인하세요:
터미널 창
```
find . -type f -size +10M
```
업로드 URL 만료 여부 확인
- 업로드 URL은 1시간 후 만료됩니다
- URL 만료 에러가 발생하면 빌드 명령어를 다시 실행하세요

“10분 후 빌드 시간 초과”

증상:

빌드가 최대 허용 시간을 초과함
상태 표시 timeout

해결 방법:

의존성 최적화
- 사용하지 않는 npm 패키지 제거
- 사용 npm prune --production 빌드 시작 전
빌드 중 네트워크 문제 확인
- 일부 의존성은 빌드 중 대용량 파일을 다운로드할 수 있음
- lock 파일로 프리캐싱 고려

네이티브 의존성 검토

# iOS - check Podfile for heavy dependencies
cat ios/App/Podfile

# Android - check build.gradle
cat android/app/build.gradle

고객 지원 문의
- 앱에 실제로 더 많은 시간이 필요한 경우
- 특정 유스케이스에 맞춰 제한을 조정할 수 있습니다

인증 문제

“API key invalid” 또는 “Unauthorized”

증상:

인증 오류로 빌드가 즉시 실패
401 또는 403 에러

해결 방법:

API 키가 올바른지 확인

# Test with a simple command
bunx @capgo/cli@latest app list

API 키 권한 확인
- 키에 있어야 할 write 또는 all 권한
- Capgo dashboard의 API Keys에서 확인

API 키가 제대로 읽히는지 확인

# Check environment variable
echo $CAPGO_TOKEN

# Or check your saved credentials file
cat ~/.capgo-credentials/credentials.json   # global
cat .capgo-credentials.json                 # local (--local)

다시 인증하기
터미널 창
```
bunx @capgo/cli@latest login
```

“App not found” 또는 “No permission for this app” 오류

증상:

인증은 성공했으나 앱 관련 오류가 발생하는 경우

해결 방법:

앱 등록 여부 확인
터미널 창
```
bunx @capgo/cli@latest app list
```
App ID 일치 여부 확인
- 검증 capacitor.config.json appId
- 명령어에 올바른 app ID가 사용되었는지 확인
조직(Organization) 액세스 권한 확인
- 올바른 조직에 속해 있는지 확인
- API 키에 앱 조직에 대한 액세스 권한이 있어야 합니다

iOS 빌드 문제

“Code 서명 실패”

증상:

code 서명 단계에서 빌드 실패
인증서 또는 프로필 관련 Xcode 에러

해결 방법:

인증서 유형과 빌드 유형 일치 여부 확인
- Development 빌드에는 Development 인증서 필요
- App Store 빌드에는 Distribution 인증서 필요

인증서와 프로필 일치 여부 확인

# Decode and inspect your certificate
echo $BUILD_CERTIFICATE_BASE64 | base64 -d > cert.p12
openssl pkcs12 -in cert.p12 -nokeys -passin pass:$P12_PASSWORD | openssl x509 -noout -subject

Provisioning profile 유효성 확인
- 만료 날짜 확인
- App ID 포함 여부 확인
- 인증서 포함 여부 확인
자격 증명 재생성
- 기존 인증서/프로파일 삭제
- Apple Developer 포털에서 새로 생성
- 재인코딩 및 환경 변수 업데이트

“Provisioning profile에 서명 인증서(signing certificate)가 포함되어 있지 않습니다”

증상:

Xcode가 프로파일에서 인증서를 찾을 수 없음

해결 방법:

Apple에서 최신 프로파일 다운로드
- Apple Developer → Certificates, IDs & Profiles로 이동
- provisioning profile 다운로드
- 인증서가 포함되어 있는지 확인

프로필에 인증서가 있는지 확인

# Extract profile
echo $BUILD_PROVISION_PROFILE_BASE64 | base64 -d > profile.mobileprovision

# View profile contents
security cms -D -i profile.mobileprovision

올바른 인증서로 프로필 재생성
- Apple Developer 포털에서 프로필 편집
- distribution certificate가 선택되었는지 확인
- 다운로드 후 다시 인코딩

“App Store Connect 인증에 실패했습니다”

증상:

TestFlight 업로드 실패
API 키 오류

해결 방법:

API 키 자격 증명 확인
- APPLE_KEY_ID 확인 (10자여야 함)
- APPLE_ISSUER_ID 확인 (UUID 형식이어야 함)
- APPLE_KEY_CONTENT가 올바르게 base64 인코딩되었는지 확인
컴퓨터 시계 동기화
- App Store Connect 인증은 로컬 시스템 시간을 기반으로 생성되는 수명이 짧은 JWT를 사용합니다
- Apple은 만료 시간이 20분 이상 남은 토큰을 거부하므로, 미세한 시간 오차로도 유효한 키가 실패할 수 있습니다
- Windows에서는 다음을 여세요 설정 > 시간 및 언어 > 날짜 및 시간 그리고 클릭하세요: 지금 동기화
- macOS에서는 다음을 여세요: 시스템 설정 > 일반 > 날짜 및 시간 날짜 및 시간을 자동으로 설정하세요.
- Linux에서는 다음을 확인하세요: timedatectl status 필요한 경우 NTP를 활성화하세요.
- 동기화 후 Capgo build 또는 credential 명령어를 다시 실행하세요.
Apple의 API 요청용 토큰 생성 문서에서 App Store Connect 토큰 만료 규칙을 확인하세요.

API 키 로컬 테스트

# Decode key
echo $APPLE_KEY_CONTENT | base64 -d > AuthKey.p8

# Test with fastlane (if installed)
fastlane pilot list

API 키 권한 확인
- 키에는 “Developer” 이상의 역할이 필요합니다
- App Store Connect -> 사용자 및 액세스 -> 키에서 확인하세요
키가 폐기되지 않았는지 확인하세요
- App Store Connect에서 확인
- 필요한 경우 새 키를 생성하세요

iOS 27에서 앱 실행 시 크래시 발생

증상:

Xcode 27로 빌드한 앱이 iOS 27(TestFlight 또는 기기)에서 즉시 종료됨
크래시 리포트 내용: _UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

해결 방법: iOS 27 SDK로 빌드된 앱은 UIScene 라이프사이클을 적용해야 합니다. 다음을 추가하세요 SceneDelegate 및 UIApplicationSceneManifest 대상 ios/App/App/Info.plist, 또는 다음으로 빌드하세요 --xcode-version 26. 이제 Capgo가 빌드 시작 전에 해당 빌드를 차단합니다 (prescan 검사 ios/plist-scene-lifecycle-xcode27).

“Pod install 실패”

증상:

CocoaPods 설치 중 빌드 실패
Podfile 오류

해결 방법:

Podfile.lock이 커밋되었는지 확인
터미널 창
```
git status ios/App/Podfile.lock
```
로컬에서 pod install 테스트
터미널 창
```
cd ios/App
pod install
```
호환되지 않는 pod 확인
- Podfile의 버전 충돌 여부 확인
- 모든 pod이 iOS deployment target을 지원하는지 확인

pod 캐시 삭제

cd ios/App
rm -rf Pods
rm Podfile.lock
pod install
# Then commit new Podfile.lock

Android 빌드 문제

“Keystore 비밀번호가 올바르지 않습니다”

증상:

서명 단계에서 빌드 실패
keystore 관련 Gradle 에러

해결 방법:

Keystore 비밀번호 확인

# Test keystore locally
keytool -list -keystore my-release-key.keystore
# Enter password when prompted

환경 변수 확인

# Ensure no extra spaces or special characters
echo "$KEYSTORE_STORE_PASSWORD" | cat -A
echo "$KEYSTORE_KEY_PASSWORD" | cat -A

Base64 인코딩 확인

# Decode and test
echo $ANDROID_KEYSTORE_FILE | base64 -d > test.keystore
keytool -list -keystore test.keystore

“Key alias not found” 오류

증상:

Alias 오류로 서명 실패

해결 방법:

Keystore alias 목록 조회

keytool -list -keystore my-release-key.keystore

Alias가 정확히 일치하는지 확인
- Alias는 대소문자를 구분합니다
- KEYSTORE_KEY_ALIAS 오타 확인

Keystore에서 올바른 alias 사용

# Update environment variable to match
export KEYSTORE_KEY_ALIAS="the-exact-alias-name"

“Gradle build failed” 오류

증상:

일반적인 Gradle 오류
컴파일 또는 의존성 문제

해결 방법:

로컬에서 먼저 빌드 테스트

cd android
./gradlew clean
./gradlew assembleRelease

누락된 의존성 확인
- build.gradle 파일 검토
- 모든 플러그인이 dependencies에 포함되었는지 확인

Gradle 버전 호환성 확인

# Check gradle version
cat android/gradle/wrapper/gradle-wrapper.properties

Gradle 캐시 삭제

cd android
./gradlew clean
rm -rf .gradle build

“Play Store upload failed” 오류

증상:

빌드는 성공했으나 upload 실패
서비스 계정 오류

해결 방법:

서비스 계정 JSON 확인

# Decode and check format
echo $PLAY_CONFIG_JSON | base64 -d | jq .

서비스 계정 권한 확인
- Play Console → 설정 → API 액세스 이동
- 서비스 계정에 앱 액세스 권한이 있는지 확인
- “테스트 트랙에 출시” 권한 부여
Play Console에 앱이 설정되었는지 확인
- Play Console에 앱이 먼저 생성되어 있어야 합니다
- 최초 1회는 APK를 수동으로 upload해야 합니다
API 활성화 여부 확인
- Google Play Developer API를 활성화해야 합니다
- Google Cloud Console 확인

일반적인 문제

“Job not found” 또는 “Build status unavailable” 오류

증상:

빌드 상태를 확인할 수 없음
Job ID 오류

해결 방법:

잠시 후 다시 시도
- Build job 초기화에 몇 초 정도 걸릴 수 있습니다
Job ID가 올바른지 확인
- 초기 빌드 응답에서 job ID를 확인하세요
빌드 만료 여부를 확인하세요
- 빌드 데이터는 24시간 동안 유지됩니다

“Project sync failed” 오류

증상:

컴파일 시작 전 빌드 실패
파일 누락 오류

해결 방법:

로컬에서 Capacitor sync 실행
터미널 창
```
bunx cap sync
```
모든 native 파일이 커밋되었는지 확인하세요
터미널 창
```
git status ios/ android/
```
gitignore된 native 파일이 있는지 확인하세요
- .gitignore 검토
- 중요한 config 파일이 무시되지 않았는지 확인하세요

“빌드는 성공했지만 출력이 보이지 않음”

증상:

Build는 성공으로 표시되지만 다운로드 링크가 없음

해결 방법:

Build 설정 확인
- Artifact 저장소가 설정되지 않았을 수 있습니다
- 빌드 결과물에 접근할 수 없는 경우 지원팀에 문의하세요
iOS TestFlight 제출 시
- App Store Connect 확인
- 업로드 후 처리까지 5~30분 정도 소요될 수 있습니다
Android Play Store의 경우
- Play Console → 테스트 → 내부 테스트 확인
- 처리까지 몇 분 정도 소요될 수 있습니다

빌드는 성공했지만 환경 전환 후 아티팩트가 잘못된 경우

증상:

빌드 상태: success 하지만 IPA/AAB/APK가 방금 빌드한 브랜치나 flavor와 일치하지 않는 경우
RC와 production 인증 정보를 전환한 후 Android AAB가 누락되었거나 잘못된 경우, 또는 --android-flavor
signing config이나 product flavor를 변경한 직후 빌드가 비정상적으로 빠르게 끝나는 경우

원인: Capgo가 기본적으로 앱별 빌드 캐시를 복구합니다(공용 일반 캐시를 사용하려면 cache_key 생략하세요). RC와 production이 별도의 키 없이 동일한 app ID를 공유하는 경우, 복구 과정에서 이전 환경의 컴파일된 결과물을 재사용할 수 있습니다.

해결 방법:

환경별로 별도의 캐시 키를 사용하세요 (지속적인 RC/PROD 파이프라인에 권장됨):

# Production
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=prod \
  --android-flavor production

# Staging / RC
bunx @capgo/cli@latest build request com.example.app --platform android \
  --cache-key=staging \
  --android-flavor staging

클린 빌드 한 번 강제 실행 디버깅할 때:

bunx @capgo/cli@latest build request com.example.app --platform android --no-cache

API 또는 webhook 연동에서, 전달 cache_key (예를 들어 "prod") 또는 설정하여 cache_enabled: false 한 번의 클린 실행을 합니다.

자세한 내용은 빌드 캐시 전체 옵션 레퍼런스를 확인하세요.

CI/CD 관련 문제

GitHub Actions: “Command not found” 오류

증상:

bunx @capgo/cli@latest … CI에서 “command not found” 오류로 실패

해결 방법:

Bun를 먼저 설정하세요 어떤 bunx 사용 가능:
```
- uses: oven-sh/setup-bun@v2
```
그 다음 CLI를 실행하세요 — bunx 필요할 때만 가져오므로 전역 설치가 필요 없습니다:
```
- run: bunx @capgo/cli@latest build request com.example.app --platform android
```

GitHub Actions: “Secrets not found” 오류

증상:

빌드 시 환경 변수가 비어 있음

해결 방법:

Secrets 설정 확인
- 레포지토리 Settings → Secrets and variables → Actions로 이동
- 필요한 모든 Secrets 추가

올바른 구문 사용

env:
  CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}

Secret 이름 일치 여부 확인
- 이름은 대소문자를 구분합니다
- Secret 참조 시 오타 확인

추가 도움 받기

Verbose Logging 활성화

# Add debug flag (when available)
bunx @capgo/cli@latest build request com.example.app --verbose

Build 정보 수집

기술 지원 문의 시 다음 내용을 포함해 주세요:

사용된 Build 명령어

bunx @capgo/cli@latest build request com.example.app --platform ios

에러 메시지 (전체 출력 내용)
Job ID (build 출력 결과에서 확인)
Build 로그 (터미널 출력 전체 복사)

환경 정보

node --version
npm --version
bunx @capgo/cli@latest --version

고객 지원 문의

Discord에서: 커뮤니티 참여하기
이메일: support@capgo.app
문서: Capgo 문서

알려진 제한 사항

현재 제한 사항:

최대 빌드 시간: 10분
최대 업로드 크기: ~500MB
iOS 빌드는 24시간 Mac 대여가 필요하며, Mac에서 빌드하면 최적 사용을 위해 대기열에 추가됩니다.
빌드 아티팩트 다운로드 가능 여부는 빌드 대상과 아티팩트 스토리지 설정에 따라 달라집니다.

이러한 제한 사항은 피드백에 따라 조정될 수 있습니다.

Prescan이 내 빌드를 차단했습니다

Capgo는 업로드 전 로컬 prescan을 실행합니다. 보고된 문제를 해결하거나, 해당 check id만 무시하세요:

npx @capgo/cli@latest build request <appId> --platform ios \
  --prescan-skip ios/capacitor-server-url-shipped

전체 카탈로그를 확인하세요: Prescan 검사.

추가 리소스

시작하기 - 초기 설정 가이드
설정 옵션 - CLI 플래그 포함 --cache-key 및 --no-cache
iOS 빌드 - iOS 전용 설정
Android 빌드 - Android 전용 설정
Prescan 검사 - 빌드 전 검사 및 ignore 플래그 전체 목록
CLI 레퍼런스 - 전체 명령어 문서