일반적인 업데이트 문제

Capgo에서 업데이트 체크가 실패할 때, 일반적으로 Capgo이 반환됩니다. error code와 함께 message 에서 /updates 응답에 포함된 경우.

이 페이지는 가장 일반적인 실패와 가장 빠른 수정 방법을 설명합니다.

• no_new_version_available 먼저 읽어보세요
• 는 일반 상태이며, 실패가 아닙니다. error 많은 '업데이트가 발견되었지만 적용되지 않았습니다' 보고는 캐시 지연이 아닌 정책/구성 거부로, 특히 응답에 명시적인 code이 포함된 경우에 특히 그렇습니다.
• 문제를 재현하는 동안 요청/응답 세부 정보를 보려면 사용하세요. npx @capgo/cli@latest app debug 일반적인 실패 코드

일반적인 실패 코드

disable_auto_update_to_major

채널이 주요 업그레이드를 차단하고 (

) 목표 번들 주요 버전이 기기 기본 버전보다 높습니다.disable_auto_update = major일반적인 증상

with

version: 1.0.8 기기에서 기본 old: 0.0.0 , 따라서 주요 업그레이드는 거부됩니다. 0.0.0이러한 문제를 해결하려면

해석 방법

백엔드에서는 장치 기본 버전과 목표 버전을 비교합니다. old 목표 버전이 version.

• , 기본 버전의 메이저 버전이 1.0.1(예를 들어 1 , 기본 버전의 메이저 버전이 1.0.0).
• (예를 들어 10.0.1수정 옵션 A (권장): 장치 기본 버전의 메이저 버전을 맞춥니다. 10 설정 10.0.0).

Fix option A (recommended): align device baseline major

in plugins.CapacitorUpdater.version __CAPGO_KEEP_0__ capacitor.config.* 그것은 MAJOR 배포하고 싶은 버전의 번들 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

원인

채널 정책이 제공되는 업데이트보다 더 엄격합니다.minor 해결 patch현재 정책과 호환되는 번들을 업로드하거나

__CAPGO_KEEP_0__에서 채널 정책을 변경하세요.

• 관련 문서:
• change channel policy in 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

원인

자연적인 baseline 이하로 다운그레이드가 불가능합니다.

Fix

• 자연적인 baseline 이상의 버전을 업로드하거나, "자연적인 baseline 이하로 다운그레이드 방지" 옵션을 해당 채널에 비활성화합니다.
• 관련 문서:

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

• 섹션 제목 “cannot_update_via_private_channel”

cannot_update_via_private_channel

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

Fix

다른 채널을 사용하거나, 채널을 공개화/장치 자체 할당을 허용하세요.

• Related docs:
• Version Targeting: Auto-Downgrade Prevention

관련 문서:

• 채널: 앱에서 setChannel() 사용

unknown_version_build / semver_error

원인

기기 기본 버전이 없거나 유효하지 않은 semver입니다.unknown수정

유효한 semver인

• 기기 앱을同步하고 재빌드하세요. plugins.CapacitorUpdater.version 관련 문서: 1.2.3.
• 채널: 채널 버전과 채널

Channels:

• Bundle Versioning and Channels
• 문제 해결: 업데이트가 적용되지 않음

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

원인

채널이 현재 빌드 유형 또는 런타임 대상과 일치하지 않습니다.

수정

• 채널 옵션 (allow_prod, allow_dev, allow_device, allow_emulator)을 테스트 대상과 일치시킵니다.

key_id_mismatch

원인

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

수정

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

no_channel / null_channel_data

원인

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

수정

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

채널

• on_premise_app

on_premise_app

protectedTokens

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

1. Capgo에 앱 ID가 존재하지 않습니다. — 기기에서 전송된 app_id 앱이 내부 서버로 표시되어 있습니다.
2. — 앱이 있지만 자체 호스팅 업데이트로 구성되어 있으므로 — the app exists but is configured for self-hosted updates, so the Capgo cloud endpoint refuses to serve it.
3. — 앱의 조직이 더 이상 활성 구독을 가지고 있지 않습니다. 일반적인 오류

타자 오류가 있습니다.

( plugins.CapacitorUpdater.appId (in capacitor.config.tsCapgo에서 등록된 앱 ID와 일치하지 않거나, Capgo 대시보드에 표시된 것과 일치하지 않는 경우입니다. 백엔드는 '알 수 없는 앱'과 '온프레미스 앱'을 구분할 수 없으므로 code과 같은 오류를 반환합니다.

Fix

• Verify the app_id Capgo 대시보드에 표시된 것과 정확히 일치합니다 (대/소문자 구분).
• __CAPGO_KEEP_0__에 앱이 등록되지 않은 경우 npx @capgo/cli@latest app add.
• __CAPGO_KEEP_0__ 클라우드 URL 대신 자체 호스팅된 업데이트 엔드포인트를 설정하는 경우 plugins.CapacitorUpdater.updateUrl Capgo 플랜이 만료된 경우 플랜을 갱신하거나 업그레이드하세요.
• 빠른 진단 체크리스트

빠른 진단 체크리스트 섹션

1. 빌드에 대한 앱 ID 및 채널이 정확한지 확인하세요.
2. Confirm CapacitorUpdater.version 설치된 네이티브 앱 버전과 일치합니다.
3. (disable_auto_update)에 명시된 채널 정책을 확인합니다.
4. Confirm platform/build target toggles allow this device.
5. )에 명시된 플랫폼/빌드 대상 설정이 이 기기를 허용합니다. npx @capgo/cli@latest app debug and read backend error code.

백엔드 에러를 읽고 __CAPGO_KEEP_0__을 실행합니다.

• '더 많은 도움이 필요하세요?'라는 섹션입니다.
• 문제 해결