-8600~-8611, -8624 (모바일 SDK 스토리지 입출력 에러)
모바일 SDK가 다운로드 파일 및 데이터베이스(DB)를 읽고 쓰는 과정에서 발생하는 파일 시스템 에러입니다. 파일 입출력 및 데이터베이스 상태에 따라 원인이 나뉘므로 연동 환경을 점검하세요.
에러 코드 목록
| 에러 코드 | 타입 | 설명 |
|---|---|---|
| -8600 | ERROR_CREATE_DIRECTORY | 디렉터리 생성 실패 |
| -8601 | ERROR_CREATE_FILE | 파일 생성 실패 |
| -8602 | ERROR_SAVE_DATA | 파일 데이터 저장 실패 |
| -8603 | ERROR_OPEN_DB | DB 파일 열기 실패 |
| -8604 | ERROR_CREATE_TABLE | DB 테이블 생성 실패 |
| -8605 | ERROR_SELECT_TABLE | DB 테이블 조회 실패 |
| -8606 | ERROR_DELETE_RECORD | DB 레코드 삭제 실패 |
| -8607 | ERROR_INSERT_RECORD | DB 레코드 추가 실패 |
| -8608 | ERROR_OPEN_FILE | 파일 열기 실패 |
| -8609 | ERROR_OUT_OF_MEMORY | 메모리 부족으로 인한 처리 실패 |
| -8610 | ERROR_READ_FILE | 파일 읽기 실패 |
| -8611 | ERROR_WRITE_FILE | 파일 쓰기 실패 |
| -8624 | ERROR_UPDATE_RECORD | DB 레코드 업데이트 실패 |
원인 A: 저장소 접근 권한 없음
애플리케이션이 디바이스의 외부 저장소(SD카드)나 특정 디렉터리에 접근하여 데이터를 쓸 수 있는 물리 권한이 없는 경우에 발생합니다.
- Android: Android 6.0(API 23) 이상 환경에서 런타임 권한을 명시적으로 획득하지 못했거나, Android 10(API 29) 이상의 범위 지정 저장소(Scoped Storage) 보안 정책에 위배되어 외부 저장소 직접 접근이 제한되는 현상입니다.
- iOS: 시스템 앱 샌드박스 내부 공간(
Documents,Library폴더 등)이 아닌 보안 권한이 제한된 외부 경로를KollusStorage저장 주소로 잘못 지정한 경우입니다.
진단 및 해결 방법
- Android: 애플리케이션의 현재 외부 저장소 쓰기 권한 할당 상태를 검사하고, 타깃 API 버전에 맞는 미디어 스토리지 접근 정책을 파악하세요.
// Android 6.0 이상 - 런타임 권한 부여 여부 확인
if (ContextCompat.checkSelfPermission(this,
Manifest.permission.WRITE_EXTERNAL_STORAGE)
!= PackageManager.PERMISSION_GRANTED) {
// 사용자에게 권한 요청
ActivityCompat.requestPermissions(this,
new String[]{Manifest.permission.WRITE_EXTERNAL_STORAGE}, REQ_CODE);
}
- iOS:
KollusStorage인스턴스의 저장 경로 설정이 올바른지 확인하세요.
원인 B: 디바이스 저장 공간 부족
디바이스의 저장 공간이 없 어 파일 생성 및 쓰기(Write)가 불가능한 경우 발생합니다.
용량 부족 상태에서 다운로드를 요청하면 해당 오류 코드와 함께 -8623(ERROR_STORAGE_FULL) 에러가 발생합니다.
해결 방법
다운로드를 시작하기 전에 아래 예시를 참고하여 디바이스의 여유 공간 크기를 사전에 검사하세요.
- Android
long available = new File(downloadPath).getUsableSpace();
// available이 충분한지 확인 후 다운로드 시작
- iOS
let freeSpace = DiskStatus.freeDiskSpaceInBytes
if freeSpace < requiredBytes {
// 디바이스 저장 공간 부족 안내
}
사용자 안내 (예시)
"저장 공간이 부족합니다. 불필요한 파일을 삭제 후 다시 시도해 주세요."
원인 C: DB 파일 손상
앱 강제 종료 또는 비정상 종료, 다운로드 도중 저장소의 물리적 분리(외장 SD카드 강제 탈거) 등으로 인해 내부 SQLite 데이터베이스가 손상된 경우 발생합니다. 주로 -8603(DB 열기 실패) 및 -8604(테이블 생성 실패) 패턴으로 리턴됩니다.
해결 방법
손상된 DB 파일을 삭제한 뒤 재초기화 로직을 트리거해야 합니다. 이 프로세스를 진행하면 다운로드된 콘텐츠 목록이 초기화되므로 사용자에게 재다운로드를 안내해야 합니다.
- Android:
KollusStorage인스턴스 해제 → DB 파일 삭제 → 재생성
// Android DB 파일 객체 생성 및 파일 삭제
File dbFile = new File(context.getFilesDir(), "kollus_storage.db");
if (dbFile.exists()) dbFile.delete();
// 삭제 이후 KollusStorage 재초기화
사용자 안내 (예시)
"데이터 오류가 발생했습니다. 앱을 재시작하거나 콘텐츠를 다시 다운로드해 주세요."
공통 진단 가이드
입출력 예외 에러 발생 시 아래 체크리스트를 바탕으로 현상을 파악하고 대응하세요.
- -8623(
ERROR_STORAGE_FULL) 에러가 동시에 발생했나요? - 최초 설치 직후이거나 Android 버전을 업데이트한 후 에러가 발생했나요?
- 정상적으로 동작하던 디바이스에서 갑자기 에러가 발생했나요?
- 위 3가지 범주에 속하지 않나요?
- 상세 에러 코드, 디바이스 OS 버전, 디바이스 모델명, 재현 방법 등을 수집하여 기술 지원팀(PE, tech_support@catenoid.net)으로 문의하세요.