본문 바로가기

일반적인 업데이트 문제

GitHub

업데이트 확인에 실패하면 Capgo는 보통 error code 및 message 플러그인의 /updates 응답을 반환합니다. 이 페이지에서는 가장 흔한 실패와 가장 빠른 해결 방법을 설명합니다.

  • no_new_version_available 실패가 아니라 정상 상태입니다.
  • “업데이트를 찾았지만 적용되지 않음” 리포트의 상당수는 캐시 지연이 아니라 정책/설정상 거부이며, 특히 응답에 명시적인 error code
  • 사용 npx @capgo/cli@latest app debug 문제를 재현하면서 요청/응답 세부 정보를 확인하세요.

자주 발생하는 실패 코드

“자주 발생하는 실패 코드” 섹션

provider_infrastructure_request_blocked

“provider_infrastructure_request_blocked” 섹션

원인

앱에 프로바이더 인프라 요청 차단 활성화되어 있고 요청이 알려진 Google 또는 Apple 데이터센터 IP 대역에서 시작된 경우입니다. Capgo는 다음에서 이러한 요청을 차단합니다. /updates, /stats, 그리고 /channel_self 프로바이더에서 발생한 트래픽이 디바이스 트래픽으로 처리되지 않도록 방지합니다.

해결 방법

  • 일반 사용자 네트워크 환경의 물리적 디바이스에서 업데이트를 재현하세요.
  • 이 보호 기능이 활성화된 동안에는 updater, stats, channel-self 체크에 클라우드 호스팅 프로브나 프로바이더 데이터센터 러너를 사용하지 마세요.
  • 해당 트래픽이 의도된 것이라면 앱의 정보 탭을 열고 프로바이더 인프라 요청 차단을(를) 끄세요. 테스트가 완료되면 다시 활성화하세요.

새 앱에는 기본적으로 이 보호 기능이 활성화되어 있습니다. 해당 설정이 도입되기 전에 생성된 앱은 사용자가 활성화할 때까지 비활성화 상태로 유지됩니다.

응답 상세 정보

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

disable_auto_update_to_major

“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 major는 반드시 1 (예를 들어 1.0.0).
  • 만약 target이 10.0.1라면, baseline major는 반드시 10 (예를 들어 10.0.0).

해결 방법 A (권장): 기기 baseline major를 맞추세요

설정 plugins.CapacitorUpdater.version 에서 capacitor.config.* 그것이 메이저 전달하려는 번들 MAJOR과 일치하도록 (예: 1.0.0 위해 1.0.1, 10.0.0 위해 10.0.1).

그 후 이 설정을 설치된 앱에 한 번 적용하세요:

  1. 실행 npx cap sync.
  2. 네이티브 앱을 다시 빌드하고 재설치하세요.

수정 옵션 B: 채널 정책 완화

채널 설정에서 크로스 메이저 자동 업데이트를 허용합니다(해당 롤아웃 전략이 의도된 경우에만).

관련 문서:

disable_auto_update_to_minor / disable_auto_update_to_patch

“disable_auto_update_to_minor / disable_auto_update_to_patch” 섹션

원인

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

  • minor 타겟 번들의 메이저 또는 마이너 버전이 디바이스 네이티브 베이스라인과 다르면 차단됩니다(version_build). 예: 1.2.3 -> 1.3.0 차단됨.
  • patch 메이저, 마이너, 패치 번호 변경을 모두 차단합니다 version_build. 접미사(suffix)만 변경할 수 있으며, 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

“disable_auto_update_to_metadata” 섹션

원인

채널이 메타데이터 기반 타겟팅을 사용하며 (version_number) 그리고 디바이스 베이스라인이 요구 수준보다 낮습니다 min_update_version.

해결 방법

  • 기기 베이스라인(CapacitorUpdater.version)을 설치된 네이티브 앱 버전과 일치시키거나
  • 채널 min_update_version 전략을 조정하세요.

관련 문서:

disable_auto_update_under_native

“disable_auto_update_under_native” 섹션

원인

채널은 네이티브 베이스라인보다 낮은 버전으로의 다운그레이드를 방지합니다.

해결 방법

  • 네이티브 베이스라인보다 크거나 같은 버전의 번들을 업로드하거나
  • 해당 채널의 “네이티브 이하” 다운그레이드 보호를 비활성화하세요.

관련 문서:

cannot_update_via_private_channel

“cannot_update_via_private_channel” 섹션

원인

선택된/기본 채널에서 디바이스 자체 할당이 허용되지 않습니다.

해결 방법

  • 자체 할당이 활성화된 다른 채널을 사용하거나
  • 채널을 공개하거나 자체 할당을 활성화하세요.

관련 문서:

unknown_version_build / semver_error

“unknown_version_build / semver_error” 섹션

원인

기기 기준 버전이 없습니다 (unknown) 또는 유효한 semver를.

해결 방법

  • 설정 plugins.CapacitorUpdater.version 일정 유효한 semver를 같은 1.2.3.
  • 네이티브 앱을 동기화하고 다시 빌드하세요.

관련 문서:

unsupported_plugin_version

“unsupported_plugin_version” 섹션

원인

업데이터 플러그인 버전이 현재 백엔드 요구사항에 비해 너무 오래되었습니다.

해결 방법

  • 업그레이드 @capgo/capacitor-updater.
  • 실행 npx cap sync.
  • 네이티브 앱을 다시 빌드하고 재설치하세요.

disabled_platform_ios / disabled_platform_android

“disabled_platform_ios / disabled_platform_android” 섹션

원인

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

해결 방법

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

disable_prod_build / disable_dev_build / disable_device / disable_emulator

“disable_prod_build / disable_dev_build / disable_device / disable_emulator” 섹션

원인

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

해결 방법

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

원인

Bundle 암호화 키와 디바이스 키가 다릅니다.

해결 방법

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

no_channel / null_channel_data

“no_channel / null_channel_data” 섹션

원인

디바이스에 유효한 채널이 확인되지 않았습니다.

해결 방법

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

관련 문서:

원인

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

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

흔한 실수

오타: plugins.CapacitorUpdater.appId ( capacitor.config.ts) 또는 Capgo 대시보드에 등록된 앱 ID와 일치하지 않는 경우입니다. 백엔드는 '알 수 없는 앱'과 '온프레미스 앱'을 구분할 수 없어 동일한 오류 code를 반환합니다.

해결 방법

  • 다음을 확인하세요: app_id Capgo 대시보드에 표시된 내용과 정확히 일치해야 합니다(대소문자 구분).
  • 앱이 아직 등록되지 않았다면 다음을 실행하세요. npx @capgo/cli@latest app add.
  • 앱이 의도적으로 온프레미스로 운영되는 경우, 다음을 설정하세요. plugins.CapacitorUpdater.updateUrl Capgo 클라우드 URL 대신 자체 호스팅된 업데이트 엔드포인트를 지정하세요.
  • 조직 플랜이 만료된 경우, 플랜을 갱신하거나 업그레이드하세요.

빠른 진단 체크리스트

“빠른 진단 체크리스트” 섹션
  1. 빌드용 앱 ID와 채널이 올바른지 확인하세요.
  2. 확인 CapacitorUpdater.version 설치된 네이티브 앱 버전과 일치합니다.
  3. 채널 정책(disable_auto_update)이 의도한 롤아웃과 일치하는지 확인하세요.
  4. 플랫폼/빌드 대상 토글이 이 기기를 허용하는지 확인하세요.
  5. 실행 npx @capgo/cli@latest app debug 그리고 백엔드 오류 code를 확인하세요.

더 도움이 필요하신가요?

“더 도움이 필요하신가요?” 섹션

자주 발생하는 업데이트 문제에서 계속하기

“Common Update Problems에서 계속하기” 제목의 섹션

사용 중이라면 일반적인 업데이트 문제 네이티브 플러그인 작업을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-updater 사용하기 네이티브 기능의 경우 @capgo/capacitor-updater 사용하기에서, Capgo 플러그인 디렉토리 Capgo Plugin Directory의 제품 워크플로우에 맞춰, Capgo의 Capacitor 플러그인 Capgo의 Capacitor 플러그인 구현 상세 내용에 대해서는, 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트 구현 상세 내용에 대해서는, Ionic Enterprise 플러그인 대안 Ionic Enterprise 플러그인 대안의 제품 워크플로우에 대해서는.