동기화 오류

이 페이지의 내용

개요

동기화 프로토콜 오류
Flexible Sync 오류
MongoDB 번역기 오류
MongoDB 연결 오류
동기화 클라이언트 오류
동기화 오류 처리
클라이언트 로그 수준 설정

Atlas Device Sync, Atlas 에지 서버, 데이터 API 및 HTTPS 엔드포인트는 더 이상 사용되지 않습니다. 자세한 내용은 지원 중단 페이지를 참조하세요.

개요

Atlas Device Sync를 사용하여 애플리케이션을 개발하는 동안 오류가 발생할 수 있습니다. 이 섹션에서는 일반적인 동기화 오류를 나열하고 이를 처리하는 방법을 설명합니다.

참고

이 페이지에 나열되지 않은 오류가 발생하면 지원 티켓 을 제출할 수 있습니다.

동기화 프로토콜 오류

다음 표에서는 Device Sync 프로토콜 오류와 이러한 오류를 처리하는 방법을 설명합니다. Atlas App Services는 Device Sync 로그에 오류를 보고합니다.

오류 이름	설명
ErrorBadClientFileIdent	이 오류는 클라이언트가 Device Sync를 종료했다가 다시 활성화한 후 서버가 액세스할 수 없는 영역 파일을 사용할 때 발생합니다. 이 오류는 클라이언트 재설정을 트리거합니다. 이 오류를 복구하려면 클라이언트 재설정을 수행합니다.
ErrorClientFileUserMismatch	이 오류는 클라이언트가 지정된 사용자가 아닌 ID와 연결된 영역 파일을 동기화하려고 시도했음을 나타냅니다. 이 문제는 사용자가 오프라인 상태일 때 Device Sync가 종료되었다가 다시 활성화되어 이전 ID가 무효화되는 경우에 발생할 수 있습니다. 이 오류를 복구하려면 로컬 영역 파일을 삭제한 다음 영역을 다시 엽니다.
ErrorDivergingHistories	이 오류는 클라이언트가 서버 영역과 동기화 기록이 다른 영역 파일을 동기화하려고 시도했음을 나타냅니다. 이 문제는 사용자가 오프라인 상태일 때 Device Sync가 종료되었다가 다시 활성화되어 이전 동기화 기록이 무효화되는 경우에 발생할 수 있습니다. 이 오류는 클라이언트 재설정을 트리거합니다. 이 오류를 복구하려면 클라이언트 재설정을 수행합니다.
ErrorPermissionDenied	이 오류는 특정 요청에 대해 사용자의 데이터 액세스 권한이 충분하지 않을 때 발생합니다. 이는 사용자가 읽기 권한 없이 영역을 열려고 하거나 쓰기 권한 없이 데이터를 수정하려고 시도하는 경우 발생할 수 있습니다. 이 오류를 해결하려면 규칙을 검토하여 사용자에게 적절한 데이터 액세스 권한이 있는지 확인하세요.
ErrorOtherError	이 오류는 보다 구체적인 오류 항목에 포함되지 않는 내부 오류를 나타냅니다. 예를 들어, 무료 계층 Atlas 클러스터의 스토리지 한도에 도달했을 때 해당 오류가 발생할 수 있습니다.

Flexible Sync 오류

앱에서 Flexible Sync를 사용할 때 다음과 같은 오류가 발생할 수 있습니다.

오류 이름

설명

ErrorBadQuery

이 오류는 클라이언트 쿼리가 유효하지 않거나 잘못된 형식임을 나타냅니다. 이 오류에는 쿼리가 잘못된 이유에 대한 세부 정보를 제공하는 메시지가 포함되어 있습니다.

이 오류를 복구하려면 쿼리 구문 이 올바른지, 서버에서 지원되는 쿼리 연산자를 사용하고 있는지 확인해야 할 수 있습니다. 또한 Flexible Sync 구성에서 쿼리 가능 필드 를 쿼리하고 있는지 확인합니다. 쿼리에서 인덱싱된 쿼리 가능 필드를 사용하는 경우 인덱싱된 쿼리 가능 필드에 대한 유효한 클라이언트 사이드 쿼리의 요구 사항을 충족하는지 확인하세요.

LimitsExceeded

이 오류는 사용 중인 쿼리가 크기 제한인 256 KB를 초과했음을 나타냅니다.

이 오류를 복구하려면 쿼리의 데이터가 허용 가능한 크기 제한 내에 있도록 쿼리를 재구성합니다.

ErrorServerPermissionsChanged

이 오류는 파일 ident를 마지막으로 사용한 이후 파일 ident에 대한 서버 권한이 변경되었음을 나타냅니다.

이 오류는 클라이언트 재설정을 트리거합니다. 이 오류를 복구하려면 클라이언트 재설정을 수행합니다.

ErrorInitialSyncNotCompleted

이 오류는 초기 동기화가 완료되기 전에 클라이언트가 세션을 열려고 했음을 나타냅니다. 앱이 방금 Sync를 활성화했고 아직 Sync 기록을 작성하는 중일 때 이 문제가 발생할 수 있습니다.

클라이언트는 이 프로세스가 완료될 때까지 다시 연결을 시도합니다. 그러면 이 오류가 해결되고 동기화가 정상적으로 작동하기 시작합니다.

ErrorCompensatingWrite

이 오류는 치명적이지 않으며, 클라이언트가 '불법적인' 쓰기를 시도할 때 발생합니다. 다음은 불법적인 쓰기 작업으로 간주됩니다:

구독을 열기 전에 객체 생성.
클라이언트의 쿼리 뷰 외부에 있는 객체 생성. '쿼리 뷰'에는 클라이언트의 구독과 클라이언트의 읽기 권한이 모두 포함됩니다.
클라이언트의 쿼리 뷰 외부에 있는 객체 수정.
클라이언트에 쓰기 권한이 없는 객체나 필드를 생성, 삭제 또는 수정.
클라이언트가 쓰기 작업 후 해당 객체나 필드에 대한 쓰기 권한을 잃는 방식으로 객체 수정.
기존 객체의 인덱싱된 쿼리 가능 필드 값 업데이트.

로컬 영역에는 '불법적인' 쓰기에 대한 개념이 없기 때문에 로컬 쓰기 작업의 경우 항상 성공합니다. 동기화 시 서버에서 불법적인 쓰기를 감지합니다. 그러면 서버가 변경 사항을 취소합니다. '보상 쓰기(compensating write)'라고 하는 실행 취소 작업은 클라이언트로 다시 동기화되어 클라이언트의 영역에 발생한 불법적인 쓰기를 제거합니다. 또한 서버는 이 오류를 전송하여 클라이언트에게 무슨 일이 발생했는지 알립니다.

해당 객체에 대한 불법적인 쓰기가 발생한 시점과 이에 대한 보상 쓰기가 발생한 시점 사이에 수행된 모든 로컬 쓰기는 손실됩니다.

예제

다음 의사(pseudo) 코드 예시를 살펴보세요:

obj1.fieldA = 10 // illegal due to field-level permissions
obj1.fieldB = 5 // legal
DELETE obj1 // legal
DELETE obj2 // legal

여기서 사용자는 fieldA에 쓸 수 있는 권한이 없음에도 불구하고 쓰기를 시도합니다. 이는 불법적인 쓰기입니다. 그런 다음 사용자는 동일한 객체에 대해 합법적 쓰기를 두 번 수행하고, 다른 객체에 대해 또 다른 합법적인 쓰기를 수행합니다. obj1.fieldA의 불법적인 쓰기에 대한 보상 쓰기를 수신하면 해당 객체에 대한 두 번의 합법적인 쓰기 후속 작업이 손실됩니다. 최종적으로 obj1은 그대로 유지되고 해당 객체 내 두 필드의 값은 수정이 이뤄지기 전의 값으로 되돌아갑니다. 한편 obj2의 삭제는 보상 쓰기를 야기한 불법적인 쓰기와 관련이 없으므로 해당 작업이 그대로 유지되고 obj2도 삭제된 상태로 유지됩니다.

불법적인 쓰기는 앱로그에 치명적이지 않은 오류로 표시됩니다. 불법적인 쓰기는 애플리케이션 코드가 의도하지 않은 작업을 수행하고 있음을 나타낼 수 있습니다.

다음과 같은 경우 '불법적인' 쓰기 후 ErrorCompensatingWrite 대신 ErrorWriteNotAllowed가 표시됩니다.

realm-core 12.1.0 이전의 realm-core 버전에 연결된 이전 SDK 버전을 사용하는 경우. 서버가 불법적인 쓰기를 취소하지 않으므로 수동으로 클라이언트 재설정을 수행해야 합니다.
데이터 수집이 활성화된 상태에서 컬렉션의 객체를 수정하는 경우. 해당 오류는 치명적이지 않으며 클라이언트 재설정을 트리거하지 않습니다. 서버는 불법적인 변경 사항을 건너뛰고 동기화된 MongoDB 클러스터에 적용하지 않습니다.

MongoDB 번역기 오류

Device Sync와 MongoDB Atlas 간의 변환 프로세스에서 다음과 같은 오류가 발생할 수 있습니다.

오류 이름	설명
MaxIntegrationAttempts	MongoDB 변환기가 변경 세트를 통합할 수 없으면 고정된 횟수만큼 재시도합니다. 이 오류는 변환기가 최대 재시도 횟수에 도달하여 변경 내용을 커밋할 수 없을 때 발생합니다. 이는 일반적으로 클러스터 크기가 충분하지 않아서 발생합니다. 이는 클러스터의 사용 가능한 리소스를 초과하는 매우 큰 트랜잭션으로 인해 발생할 수 있습니다. 예를 들어, 장치가 오랫동안 오프라인 상태이며 비정상적인 양의 배치된 트랜잭션을 동기화하려고 합니다. 또는 클러스터 리소스가 일반적으로 앱의 요구 사항에 충분하지 않습니다. 이 오류는 클러스터 계층을 업그레이드하여 해결할 수 있습니다. 이 오류를 방지하려면 연결된 MongoDB 클러스터가 앱의 요구 사항을 충족하는지 확인하세요. 또한 앱에서 데이터 읽기 및 쓰기 모범 사례를 사용하는지 확인해야 합니다. 자세한 내용은 Atlas 클러스터 크기 조정 및 계층 선택을 참조하세요.
MongoEncodingError	이 오류는 MongoDB Atlas 쓰기( 동기화 클라이언트가 아님)가 더 이상 앱의 스키마를 준수하지 않는 방식으로 문서를 수정할 때 발생합니다. 스키마와 일치하지 않는 문서는 동기화될 수 없으며 이러한 문서가 나타내는 객체에 대한 로컬 업데이트는 전파되지 않습니다. 자세한 내용은 동기화되지 않은 문서를 참조하세요.
TranslatorCorrectiveErasure	이 오류는 동기화된 MongoDB 클러스터가 전파된 Device Sync 변경 사항에 대한 쓰기 작업을 거부할 때 발생합니다. 이는 일반적으로 중복 키 예외로 인해 발생합니다. 즉, 두 객체가 동일한 기본 키를 사용한다는 의미입니다. 이 오류를 방지하려면 `ObjectId` 또는 `UUID`를 기본 키 값으로 사용하세요. 또는 동기화된 모든 객체가 파티션 간에도 고유한 기본 키를 갖고 있는지 확인하세요.
TranslatorFatalError - ChangeStreamHistoryLost	이 오류는 서버 측 '번역기' 프로세스가 읽기 전에 oplog의 이전 항목이 만료된 경우 발생합니다. 이러한 항목이 없으면 변환기는 MongoDB 클러스터와 Realm 객체 서버를 동등한 상태로 만들 수 없습니다. 다음과 같은 상황에서 발생할 수 있습니다: 동기화가 너무 오랫동안 일시 중지되어 항목이 oplog에서 제거된 경우. 번역기가 사용 중이던 컬렉션을 삭제한 경우. MongoDB 클러스터가 너무 오랫동안 연결 불가 상태인 경우. 무료 계층에는 공유 oplog가 있기 때문에 이 오류에 더 취약합니다. 이 오류를 해결하려면 동기화를 종료했다가 다시 활성화하세요.

MongoDB 연결 오류

새로 생성된 클러스터에서 Device Sync를 활성화하면 클러스터 URI를 구문 분석하는 작업이 실패할 수 있습니다. 이는 클러스터에 대한 SRV 레코드가 아직 전파되지 않았기 때문에 발생합니다. 두 가지 해결 방법이 있습니다:

5분 정도 기다린 후 Atlas Device Sync를 활성화하세요.
클러스터를 연결 해제했다가 다시 연결합니다.

동기화 클라이언트 오류

동기화 프로토콜은 연결된 클라이언트에 의해 오류가 발생한 것으로 보이는 경우 ERROR 메시지를 반환합니다. 각 메시지에는 코드 번호와 오류에 대한 설명이 포함되어 있습니다.

동기화 오류의 전체 목록을 보려면 오류 코드 목록 을 참조하세요. Realm 데이터베이스 코어 GitHub 리포지토리에 있습니다.