자주 발생하는 업데이트 문제

업데이트 확인에 실패하면, Capgo은 보통 다음과 같은 error code 및 message 안에 /updates 응답을 반환합니다. 이 페이지에서는 가장 빈번하게 발생하는 오류와 가장 빠른 해결 방법을 설명합니다.

먼저 읽어보세요

• no_new_version_available 오류가 아닌 정상적인 상태입니다.
• “업데이트를 찾았으나 적용되지 않음”이라는 보고의 상당수는 캐시 지연보다는 정책 또는 설정 거부로 인해 발생하며, 특히 응답에 명시적인 error code.
• 사용하세요: npx @capgo/cli@latest app debug 요청/응답 상세 내용을 확인하기 위해 이슈를 재현하는 동안.

일반적인 실패 코드

provider_infrastructure_request_blocked

원인

앱에 provider infrastructure requests 차단 설정이 활성화되어 있고, 요청이 알려진 Google 또는 Apple 데이터 센터 IP 범위에서 시작된 경우입니다. Capgo은(는) 다음에서 이러한 요청을 차단합니다. /updates, /stats, 그리고 /channel_self 프로바이더에서 발생하는 트래픽이 디바이스 트래픽으로 오인되는 것을 방지하기 위함입니다.

해결

• 일반 사용자 네트워크 환경의 실제 디바이스에서 업데이트를 재현해 보세요.
• 이 보호 기능이 활성화된 동안에는 updater, stats 또는 channel-self 체크를 위해 클라우드 기반 프로브나 프로바이더 데이터센터 러너를 사용하지 마세요.
• 해당 트래픽이 의도된 것이라면, 앱의 정보 탭을 열고 Block provider infrastructure requests를 비활성화하세요. 테스트가 완료되면 다시 활성화하면 됩니다.

새 앱은 이 보호 기능이 기본적으로 활성화되어 있습니다. 해당 설정이 도입되기 전에 생성된 앱은 직접 활성화하기 전까지 비활성 상태로 유지됩니다.

응답 상세 정보

• /updates updater 응답 규약을 유지하며 HTTP를 반환합니다 200. 본문 내용은 다음과 같습니다: error, message, kind: "blocked", 그리고 provider ("google" 또는 "apple").
• /stats 및 /channel_self HTTP를 반환합니다. 429 동일한 에러 code가 발생합니다. 이는 일시적인 재시도 문제가 아니라 의도된 정책 차단으로 간주해야 합니다.

disable_auto_update_to_major

원인

채널에서 메이저 업그레이드를 차단하고 있으며 (disable_auto_update = major) 대상 번들의 메이저 버전이 기기의 기준 버전을 초과합니다.

일반적인 증상

version: 1.0.8 함께 old: 0.0.0 기기 baseline이 보고되었음을 의미하며 0.0.0, 따라서 메이저 업그레이드는 거부됩니다.

해석 방법

백엔드는 기기 baseline과 old 및 대상 version.

• 만약 target이 1.0.1라면, baseline의 메이저 버전은 1 (예를 들어 1.0.0).
• 만약 target이 10.0.1라면, baseline의 메이저 버전은 10 (예를 들어 10.0.0).

해결 방법 A (권장): 기기 baseline의 메이저 버전을 맞추세요

설정 plugins.CapacitorUpdater.version 에서 capacitor.config.* 즉, MAJOR 버전이 배포하려는 bundle의 MAJOR 버전과 일치해야 합니다 (예: 1.0.0 다음에 해당하는 1.0.1, 10.0.0 다음에 해당하는 10.0.1).

그다음, 설치된 앱에 이 설정을 한 번만 적용하세요:

1. 실행 npx cap sync.
2. Native Build를 다시 빌드하고 재설치하세요.

해결 방법 B: 채널 정책 완화

채널 설정에서 cross-major 자동 업데이트를 허용하세요 (해당 배포 전략을 의도한 경우에만).

관련 문서:

• 버전 타겟팅: 메이저 버전 간 자동 업데이트 비활성화
• Channels: 자동 업데이트 전략 비활성화

disable_auto_update_to_minor / disable_auto_update_to_patch

원인

채널 정책이 제공되는 업데이트보다 더 엄격함 (minor 또는 patch)

• minor 대상 번들이 디바이스의 Native Build 베이스라인과 메이저 또는 마이너 버전이 다를 경우 차단 (version_build). 예시: 1.2.3 -> 1.3.0 차단됩니다.
• patch 다음 버전으로부터의 메이저, 마이너 또는 패치 번호 변경을 차단 version_build. 오직 접미사 변경만 허용됩니다. MAJOR.MINOR.PATCH 다음과 같이 유지되어야 합니다: 1.0.0-beta.1 -> 1.0.0-beta.2 또는 1.0.0+build.1 -> 1.0.0+build.2.

해결

• 현재 정책과 호환되는 번들을 업로드하거나,
• dashboard/CLI에서 채널 정책을 변경하세요.

관련 문서:

• 채널: 자동 업데이트 전략 비활성화

disable_auto_update_to_metadata

원인

채널이 메타데이터 기반 타겟팅을 사용하며 (version_number) 디바이스 베이스라인이 요구 사항보다 낮음 min_update_version.

해결

• 기기 베이스라인으로 (CapacitorUpdater.version)을 설치된 Native Build 버전과 맞추거나,
• 다음 설정을 조정하세요: min_update_version / 채널 전략.

관련 문서:

• 채널: 자동 업데이트 전략 비활성화

disable_auto_update_under_native

원인

Channel 설정이 Native Build 베이스라인보다 낮은 버전으로의 다운그레이드를 방지합니다.

해결

• Native Build 베이스라인보다 높거나 같은 버전의 bundle을 upload하거나,
• 해당 채널의 “under native” 다운그레이드 방지 기능을 비활성화하세요.

관련 문서:

• 버전 타겟팅: 자동 다운그레이드 방지

cannot_update_via_private_channel

원인

선택된/기본 채널이 디바이스의 셀프 어사인먼트(self-assignment)를 허용하지 않습니다.

해결

• 셀프 어사인먼트가 활성화된 다른 채널을 사용하거나,
• 채널을 공개로 전환하거나 셀프 어사인먼트를 활성화하세요.

관련 문서:

• Channels: 앱에서 setChannel() 사용하기

unknown_version_build / semver_error

원인

디바이스 베이스라인 버전이 누락되었거나 (unknown) 또는 유효하지 않은 semver 형식입니다.

해결

• 설정 plugins.CapacitorUpdater.version 에 대한 유효하지 않은 semver 형식입니다 예: 1.2.3.
• 동기화 후 Native Build를 다시 진행하세요.

관련 문서:

• 채널: 번들 버전 관리 및 채널 안내
• 문제 해결: 업데이트가 적용되지 않는 경우

unsupported_plugin_version

원인

Updater 플러그인 버전이 현재 백엔드 요구 사항보다 너무 낮습니다.

해결

• 해결 방법 @capgo/capacitor-updater.
• 실행 npx cap sync.
• Native Build를 다시 수행하고 앱을 재설치하세요.

disabled_platform_ios / disabled_platform_android

원인

해당 플랫폼에 대해 채널의 업데이트 기능이 비활성화되어 있습니다.

해결

• 채널에서 플랫폼 토글을 활성화하세요.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

원인

채널에서 현재 빌드 유형 또는 런타임 타겟을 허용하지 않습니다.

해결

• 채널 옵션을allow_prod, allow_dev, allow_device, allow_emulator테스트 타겟과 일치시키세요.

key_id_mismatch

원인

Bundle 암호화 키와 디바이스 키가 일치하지 않습니다.

해결

• 앱 설정과 Bundle 암호화 워크플로우에서 동일한 암호화 키/공개 키를 사용하세요.

no_channel / null_channel_data

원인

디바이스에서 유효한 채널을 찾을 수 없습니다.

해결

• 클라우드 기본 채널을 설정하거나,
• 설정하세요 defaultChannel 테스트 빌드 시,
• 디바이스에 채널 오버라이드를 할당하세요.

관련 문서:

• 채널

on_premise_app

원인

백엔드에서 HTTP 429 오류를 반환했습니다: on_premise_app. 다음 세 가지 상황에서 발생합니다:

1. Capgo에 App ID가 없음 — app_id 기기에서 전송한 ID가 등록되지 않아 백엔드에 기록이 없는 경우입니다.
2. App이 온프레미스(on-premise)로 설정됨 — 앱은 존재하지만 자체 호스팅 업데이트로 설정되어 있어, Capgo 클라우드 엔드포인트에서 요청을 거부합니다.
3. Organization 플랜이 취소됨 — 해당 앱의 조직에 더 이상 활성화된 구독이 없는 경우입니다.

흔한 실수

오타 발생 plugins.CapacitorUpdater.appId (에 있는 capacitor.config.ts) 또는 Capgo 대시보드에 등록된 app ID와 일치하지 않습니다. 백엔드에서는 “알 수 없는 앱”과 “온프레미스 앱”을 구분할 수 없으므로 동일한 code 에러를 반환합니다.

해결

• 다음 사항을 확인하세요: app_id Capgo 대시보드에 표시된 내용과 정확히 일치하는지 확인하세요 (대소문자 구분).
• 앱이 아직 등록되지 않았다면, 다음 명령어를 실행하세요: npx @capgo/cli@latest app add.
• 앱을 의도적으로 온프레미스(on-premise) 환경에서 운영한다면, 다음을 설정하세요. plugins.CapacitorUpdater.updateUrl Capgo 클라우드 URL 대신 직접 호스팅하는 업데이트 엔드포인트로 전송하세요.
• 빠른 진단 체크리스트

“빠른 진단 체크리스트” 섹션

1. 빌드에 사용된 app ID와 channel이 올바른지 확인하세요.
2. 확인 CapacitorUpdater.version 설치된 Native Build 버전과 일치합니다.
3. 채널 정책 (disable_auto_update)이 의도한 배포 방식과 일치하는지 확인하세요.
4. 플랫폼/빌드 타겟 설정이 해당 기기를 허용하는지 확인하세요.
5. 실행 npx @capgo/cli@latest app debug 그리고 백엔드 에러 code를 확인하세요.

도움이 더 필요하신가요?

• 문제 해결
• 지원받는 방법

업데이트 관련 일반적인 문제에서 계속하기

사용 중인 경우 자주 발생하는 업데이트 문제 네이티브 플러그인 작업을 계획하려면, 이를 연결하세요: @capgo/capacitor-updater 사용하기 @capgo/capacitor-updater 사용 시 네이티브 기능을 위해, Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리의 제품 워크플로우를 보려면, Capgo 제공 Capacitor 플러그인 Capgo 제공 Capacitor 플러그인의 구현 세부 사항을 보려면, 플러그인 추가 및 업데이트 플러그인 추가 및 업데이트의 구현 세부 사항을 확인하고, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우를 확인하세요.