Keep going from Common Update Problems

업데이트 체크가 실패할 때, Capgo 일반적으로 Capgo와 함께 반환합니다. error code와 함께 code가 반환됩니다. message 업데이트 중 /updates 응답. 이 페이지는 가장 일반적인 실패와 가장 빠른 해결책을 설명합니다.

먼저 읽으세요

• no_new_version_available 정상 상태입니다. 실패는 아닙니다.
• 많은 "업데이트가 발견되었지만 적용되지 않았습니다" 보고는 정책/구성 거부 rather 보다는 캐시 지연 때문이 아닙니다. 특히 응답에 명시적인 error code.
• 문제를 재현하는 동안 요청/응답 세부 정보를 확인하세요. npx @capgo/cli@latest app debug 일반적인 실패 코드

제목 "일반적인 실패 코드"

provider_infrastructure_request_blocked

원인

앱이 블록 제공자 인프라 요청 활성화되어 있고, 요청은 알려진 Google 또는 Apple 데이터 센터 IP 범위에서 시작된 것입니다. Capgo은 이러한 요청을 /updates, /stats, /channel_self 에서 차단하여 제공자에서 발생한 트래픽이 장치 트래픽으로 처리되는 것을 방지합니다.

수정

• 물리 장치에서 일반 사용자 네트워크에서 업데이트를 다시 생성하세요.
• 이 보호 기능이 활성화된 동안 업데이트기, 통계, 채널-자체 확인에 대해 클라우드 호스팅 프로브 또는 제공자 데이터 센터 러너를 사용하지 마세요.
• 그렇지 않다면, 앱의 정보 탭을 열고 블록 제공자 인프라 요청. 테스트가 완료되면 다시 활성화하세요.

새로운 앱은 기본적으로 이 보호 기능이 활성화되어 있습니다. 이전에 설정이 도입되기 전에 생성된 앱은 활성화할 때까지 이 기능이 비활성화됩니다.

응답 세부 정보

• /updates 업데이터 응답 계약을 유지하고 HTTP 200. 그들의 바디는 error, message, kind: "blocked", 그리고 provider ("google" 또는 "apple").
• /stats 또는 /channel_self HTTP 429 with the same error code. Treat this as an intentional policy block, not a transient retry condition.

disable_auto_update_to_major

원인

채널이 주요 업그레이드를 차단하고 장치 기준 버전보다 대상 패키지의 주요 버전이 높습니다.disable_auto_update = major일반적인 증상

with

version: 1.0.8 장치 기준을 보고 있기 때문에 주요 업그레이드는 거부됩니다. old: 0.0.0 해석 방법 0.0.0백엔드에서는 장치 기준 버전과 대상 버전을 비교하여 주요 버전을 비교합니다.

대상이

기준 주요 버전이 old 되어야합니다. version.

• If target is 1.0.1, baseline major must be 1 (예를 들어) 1.0.0).
• 목표가 10.0.1, 기본 버전이 10 (예를 들어) 10.0.0).

Fix 옵션 A (권장): 기기 기본 버전을

으로 설정하여 plugins.CapacitorUpdater.version 이 capacitor.config.* 이 를 맞추어 (예를 들어) 위한 1.0.0 위한 1.0.1, 10.0.0 for 10.0.1).

그런 다음 설치된 앱에 이 설정을 적용하세요:

1. 실행 npx cap sync.
2. 자연어 앱을 재구축하고 다시 설치하세요.

해결 방법 B: 채널 정책을 완화하세요.

채널 설정에서 크로스-메이저 자동 업데이트를 허용하세요 (만약 그 롤아웃 전략이 의도된 경우에만).

관련 문서:

• 버전 대상 설정: 메이저 버전을 건너 뛰는 자동 업데이트를 비활성화하세요.
• 채널: 자동 업데이트를 비활성화하는 전략

disable_auto_update_to_minor / disable_auto_update_to_patch

원인

채널 정책이 더 엄격합니다 (minor 또는 patch보다 큰 업데이트가 제안되는 것보다.

• minor 대상 번들을 대상 기기 기본 라인에 다른 주요 또는 부수적인 경우 업데이트가 차단됩니다.version_build예시: 1.2.3 -> 1.3.0 업데이트가 차단됩니다.
• patch 대상 번들이 기기 기본 라인에 다른 주요, 부수적 또는 패치 번호를 변경하는 경우 업데이트가 차단됩니다. 단, 접미사만 변경할 수 있습니다. 예를 들어, 1.2.3에서 1.2.4로 업데이트하는 경우는 허용되지만, 1.2.3에서 1.3.0으로 업데이트하는 경우는 차단됩니다. 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.

업데이트가 차단됩니다.

• 업데이트가 차단됩니다.
• change channel policy in dashboard/CLI.

업데이트가 차단됩니다.

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

disable_auto_update_to_metadata

원인

채널이 메타데이터 기반 타겟팅을 사용하고 (version_number) 기기 기준선은 요구된 것보다 낮습니다. min_update_version.

해결

• 기기 기준선 (CapacitorUpdater.version)을 설치된 네이티브 앱 버전과 일치시키거나 (
• ) 채널 전략을 조정합니다. min_update_version 관련 문서:

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

• Channels: Disable Auto Update strategies

disable_auto_update_under_native

원인

Channel은 원래 baseline 이하의 버전으로 다운그레이드하는 것을 방지합니다.

해결

• 원래 baseline 이상의 버전의 패키지를 업로드하거나, 또는 해당 채널의 다운그레이드 보호를 비활성화합니다.
• 관련 문서:

버전 목표: 자동 다운그레이드 방지

• Section titled “private_channel_update_불가”

cannot_update_via_private_channel

선택된/기본 채널은 장치 자체 할당을 허용하지 않습니다.

해결

관련 문서:

• 다른 채널을 사용하세요. self assignment이 활성화되어야 합니다.
• 채널을 공개화 하거나 self assignment을 활성화하세요.

관련 문서:

• 채널: setChannel()을 앱에서 사용하는 방법

unknown_version_build / semver_error

원인

기기 기본 버전이 누락되거나 (unknown) 또는 semver가 유효하지 않습니다. 수정.

기기 기본 버전을

• 설정 plugins.CapacitorUpdater.version to 유효한 semver 예를 들어 1.2.3.
• 자연 앱을 다시 빌드하고 동기화하세요.

관련 문서:

• 채널: 버전 관리 및 채널
• 문제 해결: 업데이트가 적용되지 않음

unsupported_plugin_version

원인

업데이터 플러그인 버전이 현재 백엔드 요구 사항에 맞지 않습니다.

수정

• 업그레이드 @capgo/capacitor-updater.
• 실행 npx cap sync.
• Rebuild and reinstall native app.

disabled_platform_ios / disabled_platform_android

원인

Channel has updates disabled for that platform.

해결

• Enable platform toggle on the channel.

disable_prod_build / disable_dev_build / disable_device / disable_emulator

원인

Channel disallows current build type or runtime target.

해결

• Align channel options (allow_prod, allow_dev, allow_device, allow_emulator)

key_id_mismatch

원인

앱 구성과 번들 암호화 워크플로우에서 사용하는 암호화 키/공개 키가 다릅니다.

해결

• 앱 구성과 번들 암호화 워크플로우에서 동일한 암호화 키/공개 키를 사용하십시오.

no_channel / null_channel_data

원인

장치에 대한 유효한 채널이 해결되지 않았습니다.

해결

• 클라우드 기본 채널을 설정하거나
• 테스트 빌드에서 defaultChannel 설정
• 장치에 대한 채널 오버라이드 할당.

관련 문서:

• 채널

on_premise_app

온프레미스 앱 섹션 제목

원인 on_premise_app백엔드에서 HTTP 429이 반환되었습니다.

1. App ID does not exist in Capgo 앱 ID가 __CAPGO_KEEP_0__에 존재하지 않습니다. app_id — 장치에서 보내는
2. 등록되지 않은ため 백엔드에 기록되지 않은 것입니다. 앱이 온프레미스 플래그로 표시되어 있습니다. — 앱이 있지만 자체 호스팅 업데이트로 구성되어 있으므로 Capgo 클라우드 엔드포인트는 이를 제공하지 않습니다.
3. __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

__CAPGO_KEEP_0__

__CAPGO_KEEP_0__ plugins.CapacitorUpdater.appId __CAPGO_KEEP_0__ capacitor.config.ts) or a mismatch with the app ID registered in the Capgo dashboard. The backend cannot distinguish “unknown app” from “on-premise app”, so it returns the same error code.

__CAPGO_KEEP_0__

• __CAPGO_KEEP_0__ app_id Capgo
• __CAPGO_KEEP_0__ npx @capgo/cli@latest app add.
• __CAPGO_KEEP_1__ plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
• 만료된 조직 플랜이 있다면, 플랜을 갱신하거나 업그레이드하세요.

빠른 진단 체크리스트

1. 빌드에 대한 앱 ID 및 채널이 정확한지 확인하세요.
2. 확인 CapacitorUpdater.version 설치된 네이티브 앱 버전과 일치하는지 확인하세요.
3. 채널 정책 (disable_auto_update)가 의도한 롤아웃과 일치하는지 확인하세요.
4. 플랫폼/빌드 대상 설정이 이 기기에 허용하는지 확인하세요.
5. 실행 npx @capgo/cli@latest app debug and read backend error code.

더 도움이 필요하세요?

• 문제 해결
• 지원 방법

다음 단계로

이러한 문제를 겪고 계신가요 Common Update Problems native 플러그인 작업을 계획하고 있습니다 Using @capgo/capacitor-updater Using @capgo/capacitor-updater Capgo Plugin Directory Capgo Plugin Directory Capacitor Capgo 플러그인 Capacitor 플러그인 Capgo 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트, 그리고 아이온 enterprise 플러그인 대체 아이온 enterprise 플러그인 대체에 대한 제품 워크플로우.