일반 업데이트 문제

When an update check fails, Capgo usually returns an error code and a message in the /updates response. This page explains the most common failures and the fastest fixes.

Read this first

• no_new_version_available is a normal state, not a failure.
• Many “update found but not applied” reports are policy/configuration refusals rather than cache lag, especially when the response includes an explicit error code.
• Use npx @capgo/cli@latest app debug while reproducing the issue to see request/response details.

Common failure codes

disable_auto_update_to_major

원인

채널이 메이저 업데이트를 차단하고( ) 장치 기준 버전보다 대상 패키지 메이저 버전이 높습니다.disable_auto_update = major일반 증상

with

version: 1.0.8 장치 기준 버전이므로 메이저 업데이트가 거부됩니다. old: 0.0.0 해석 방법 0.0.0백엔드에서는 장치 기준 버전과 대상 버전을 비교하여 메이저 버전을 비교합니다.

with

means the device reports baseline old with version.

• If target is 1.0.1, baseline major must be 1 (for 예시 1.0.0).
• If target is 10.0.1, baseline major must be 10 (for 예시 10.0.0).

Fix option A (recommended): align device baseline major

설정 plugins.CapacitorUpdater.version in capacitor.config.* 그것의 MAJOR bundle MAJOR을 전달하고 싶은 것과 일치하도록 (for 예시 1.0.0 for 1.0.1, 10.0.0 for 10.0.1).

설치된 앱에 이 설정을 적용하세요:

1. 실행 npx cap sync.
2. minor 버전 및 patch 버전까지의 자동 업데이트 기능을 비활성화합니다.

Fix option B: 채널 정책을 완화하세요

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

관련 문서:

• 버전 대상 설정: 메이저 버전 간의 자동 업데이트를 비활성화하세요
• 채널: 자동 업데이트 전략 비활성화

disable_auto_update_to_minor / disable_auto_update_to_patch

원인

채널 정책은 더 엄격합니다 (minor or patch) offered 업데이트보다.

• minor target 버블이 기기 기본선에 다른 메이저 또는 메인 버전을 가질 때 (version_build) 블록됩니다. 예를 들어. 1.2.3 -> 1.3.0 is 블록됩니다.
• patch 메이저, 메인 또는 패치 번호 변경이 version_build에서 허용되지 않습니다. 단, MAJOR.MINOR.PATCH 나 1.0.0-beta.1 -> 1.0.0-beta.2 Fix 1.0.0+build.1 -> 1.0.0+build.2.

현재 정책과 호환되는 버블을 업로드하거나

• Upload a bundle compatible with the current policy, or
• change channel policy in dashboard/CLI.

관련 문서:

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

disable_auto_update_to_metadata

원인

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

수정

• 기기 기준선 (CapacitorUpdater.version)을 설치된 네이티브 앱 버전과 일치시키거나
• 조정 min_update_version / 채널 전략.

관련 문서:

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

disable_auto_update_under_native

원인

채널이 네이티브 기준 이하로 다운그레이드 방지

해결

• 네이티브 기준 이상의 버전 업로드 또는
• 해당 채널의 “네이티브 아래” 다운그레이드 보호를 비활성화

관련 문서:

• 버전 대상 설정: 자동 다운그레이드 방지

cannot_update_via_private_channel

원인

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

수정

• 다른 채널을 사용하여 장치 할당을 허용하거나 채널을 공개 / 장치 할당을 허용하도록 하세요.
• 관련 문서:

채널: setChannel()을 사용하는 앱

• 제목 ‘unknown_version_build / semver_error’

unknown_version_build / semver_error

장치 기본 버전이 없거나( ) 또는 유효하지 않은 semver입니다.

수정unknown관련 문서: Channels: Using setChannel() from Your App.

Section titled “unknown_version_build / semver_error”

• 설정 plugins.CapacitorUpdater.version __CAPGO_KEEP_0__ 유효한 semver Sync 및 네이티브 앱을 재구축합니다. 1.2.3.
• 관련 문서:

채널: 버전 관리 및 채널

• 문제 해결: 업데이트 적용되지 않음
• 버전이 지원되지 않는 플러그인

unsupported_plugin_version

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

수정

해결

• 업그레이드 @capgo/capacitor-updater.
• 실행 npx cap sync.
• 원시 앱을 재구축하고 재설치합니다.

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)을 테스트 대상과 일치시켜라.

key_id_mismatch

원인

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

해결

• no_channel / null_channel_data

no_channel / null_channel_data

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

해결

클라우드 기본 채널을 설정하거나

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

관련 문서:

• 채널

on_premise_app

원인

백엔드에서 HTTP 429이 반환되었습니다. on_premise_app. 이 상황은 세 가지 경우에 발생합니다:

1. 앱 ID가 Capgo에 존재하지 않습니다. — 장치에서 보낸 요청은 등록되지 않았으므로 백엔드에서 이를 기록하지 못합니다. app_id Related docs:
2. 온프레미스 앱으로 표시되었습니다. — 앱이 있지만 자체 호스팅 업데이트로 구성되어 있기 때문에 Capgo 클라우드 엔드포인트는 이를 제공하지 않습니다.
3. 기업 계획이 취소되었습니다. — 앱의 기업이 더 이상 활성 구독을 가지고 있지 않습니다.

일반적인 오류

A typo in plugins.CapacitorUpdater.appId (in 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.

or a mismatch with the app ID registered in the __CAPGO_KEEP_0__ dashboard. The backend cannot distinguish “unknown app” from “on-premise app”, so it returns the same error __CAPGO_KEEP_1__.

• 수정 app_id matches exactly what is shown in the Capgo dashboard (case-sensitive).
• matches exactly what is shown in the __CAPGO_KEEP_0__ dashboard (case-sensitive). npx @capgo/cli@latest app add.
• 애플리케이션이 의도적으로 온프레미스에 있다면, __CAPGO_KEEP_0__ 클라우드 URL 대신 자체 호스팅된 업데이트 엔드포인트를 설정하세요. plugins.CapacitorUpdater.updateUrl to your self-hosted update endpoint instead of the Capgo cloud URL.
• 빠른 진단 체크리스트

빠른 진단 체크리스트

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

더 많은 도움이 필요하세요?

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

일반 업데이트 문제에서 계속

Capacitor를 사용하는 경우 일반 업데이트 문제 네이티브 플러그인 작업을 계획하고 있습니다. @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-updater를 사용하여 네이티브 기능과 연결하세요. Using @capgo/capacitor-updater Using @capgo/capacitor-updater Capgo 플러그인 디렉토리 Capgo 플러그인 디렉토리에서 제품 워크플로우를 위해 Capacitor 플러그인들에 의해 Capgo Capacitor 플러그인들에 의해 Capgo에서 구현 세부 정보를 위해 플러그인 추가 또는 업데이트 플러그인 추가 또는 업데이트에서 구현 세부 정보를 위해, Ionic Enterprise 플러그인 대체 Ionic Enterprise 플러그인 대체의 제품 워크플로우를 위해