> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ones1ght.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 트러블슈팅

> SDK 로그를 읽는 법과 증상별 확인 순서입니다. 어디서 막혔는지 코드 하나로 좁힐 수 있습니다.

## 개요

SDK 는 각 단계가 통과했는지, 무엇이 막혔는지를 **코드로** 남깁니다.

```
[I1001] 초기화 완료 — tenant=itoku
[I3001] 층 지정 — building=B1 floor=9f3a1c2e locators=4 zones=3
[I4001] 측위 시작 — visitor=v-20260820-001
```

```
[E3003] 층에 UWB 세션 없음 — floor=9f3a1c2e
```

| 접두사 | 뜻           | 언제       |
| --- | ----------- | -------- |
| `I` | 정보 — 단계 통과  | 정상 흐름 추적 |
| `E` | 에러 — 무언가 막힘 | 조치 필요    |

<Note>
  **왜 문장이 아니라 코드인가.** 문구는 판올림마다 바뀌지만 코드는 그대로입니다. 문의·문서·콘솔 필터가
  같은 값을 가리키게 하려면 고정된 식별자가 필요합니다.

  사람이 읽는 문장은 콘솔이 **보는 사람의 화면 언어로** 만들어 줍니다 — 일본 사용자의 기기에서 난
  에러도 한국인 관리자에게는 한국어로 보입니다.
</Note>

전체 코드 목록은 [에러 코드 안내](/sdk/faq/error-code)에 있습니다.

## 준비

### 앱에서 로그 보기

`onDebugLog` 에 클로저를 연결하면 SDK 가 남기는 모든 줄이 그리로 옵니다.

```swift theme={null}
OneS1ght.onDebugLog = { level, line in
    print("[OneS1ght][\(level)] \(line)")
}
```

<Warning>
  `initialize` **보다 먼저** 연결하세요. 나중에 연결하면 초기화 단계의 로그를 놓칩니다 —
  연동 초기에 가장 많이 막히는 구간이 바로 거기입니다.
</Warning>

로그를 파일로 뽑아 문의에 첨부하는 방법은 [로그 출력 방법](/sdk/faq/logging)을 보세요.

### 콘솔에서 로그 보기

앱에 붙지 않아도 됩니다. SDK 는 로그를 서버로도 올리고, 관리자는 콘솔에서 봅니다.

| 보는 사람   | 어디서                            | 무엇을                   |
| ------- | ------------------------------ | --------------------- |
| 고객사 관리자 | 콘솔 → 모바일 SDK → 관리자 도구 → 로그 분석기 | 자사 앱의 로그              |
| 통합 관리자  | 콘솔 → 서비스 관리 → SDK 관리           | 전 고객사의 로그 + 코드별 발생 건수 |

<Note>
  운영 중인 사용자 기기에서 난 문제는 이쪽으로만 볼 수 있습니다. Xcode 콘솔은 개발자 손에 기기가
  있을 때만 쓸 수 있습니다.
</Note>

## 정상 흐름은 이렇게 찍힙니다

연동이 제대로 됐다면 아래 순서로 나옵니다. **없는 줄이 곧 막힌 지점**입니다.

| 순서 | 코드      | 시점                             |
| -- | ------- | ------------------------------ |
| 1  | `I1001` | 초기화 완료                         |
| 2  | `I1002` | 프로필 연결                         |
| 3  | `I3001` | 층 지정 — 로케이터 N대, 구역 M개가 함께 찍힙니다 |
| 4  | `I4001` | 측위 시작                          |
| 5  | `I4002` | 측위 종료 — 수집한 좌표 수가 함께 찍힙니다      |

<Note>
  `I5001` 은 콘솔에서 정한 전송 주기가 기본값(4회/초)과 다를 때만 나옵니다. 안 보인다고 문제가 아닙니다.
</Note>

## 증상별로 어디부터 볼지

<AccordionGroup>
  <Accordion title="앱은 도는데 좌표가 하나도 안 나온다" icon="location-crosshairs">
    **볼 코드 —** `E3001` · `E3003` · `E4002` · `E4003`

    <Steps>
      <Step title="층을 지정했나">
        `setFloorMap` 을 부르지 않으면 파이프라인은 돌지만 좌표가 나오지 않습니다(`E3001`).
        `initialize` 는 건물·층을 조회하지 않습니다 — 단일 매장 앱이라도 한 번은 불러야 합니다.
      </Step>

      <Step title="그 층에 UWB 세션이 있나">
        `E3003` 이면 GeoSpace 쪽 설정 문제입니다. **앱 코드를 고쳐도 풀리지 않습니다.**
        `locators(_:_:)` 의 `positioningReady` 로도 확인할 수 있습니다.
      </Step>

      <Step title="로케이터 신호가 잡히나">
        측위 시작 7초 뒤 `E4003`(일부 미수신)이 뜨면 해당 로케이터의 전원·위치를 확인하세요.
        신호는 3대 이상 잡히는데 좌표가 안 나오면 `E4002` — **등록 좌표와 실제 배치 불일치**를 의심합니다.
      </Step>

      <Step title="현장 안에 있나">
        로케이터가 설치된 영역 밖에서는 좌표가 나오지 않습니다. 에러도 나지 않습니다.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="구역 이벤트가 안 온다" icon="draw-polygon">
    **볼 코드 —** `E3004`

    * 콘솔 [공간 관리](/locator/areas)에 그 층의 구역이 등록돼 있는지 확인합니다.
    * 좌표는 나오는데 진입만 안 잡힌다면 구역의 **판정 파라미터**를 봅니다 —
      특히 `inCount` 가 `0` 이면 진입이 영원히 확정되지 않습니다.
      ([SDK 영역판정](/locator/areas#sdk-영역판정))
    * 콘솔에서 방금 구역을 바꿨다면 `await OneS1ght.refreshZones()` 로 다시 받으세요.
  </Accordion>

  <Accordion title="구역에는 들어갔는데 쿠폰만 안 뜬다" icon="ticket">
    **볼 코드 —** `E5001` · `E5002`

    `onZoneEnter` 는 **기기 안 판정**이라 네트워크가 끊겨도 옵니다. `onTriggers` 는
    **서버 응답**이라 오지 않습니다. 앱 버그가 아니라 네트워크·서버 문제입니다.

    콘솔에서 그 구역에 걸린 시책이 **실행 상태**인지도 함께 확인하세요.
  </Accordion>

  <Accordion title="특정 기기에서만 안 된다" icon="mobile">
    **볼 코드 —** `E2001` · `E2002`

    iOS 27 이상 · iPhone 12 이상인지 확인합니다. `deviceAvailability` 로 사전 분기해
    미지원 기기에서는 측위 UI 를 숨기세요 — 앱 자체는 정상 동작해야 합니다.
  </Accordion>

  <Accordion title="권한 팝업이 다시 안 뜬다" icon="lock">
    **볼 코드 —** `E2003`

    이미 한 번 거부한 상태입니다. **앱에서 재요청할 수 없습니다** — 설정 앱으로 유도하세요.

    ```swift theme={null}
    UIApplication.shared.open(URL(string: UIApplication.openSettingsURLString)!)
    ```
  </Accordion>

  <Accordion title="연동하자마자 401" icon="key">
    **볼 코드 —** `E1002`

    * 키 값에 공백·줄바꿈이 섞이지 않았는지 확인합니다.
    * 콘솔에서 그 키가 **폐기**되지 않았는지 확인합니다.
    * 실행 환경(Production / Development)이 맞는지 확인합니다.

    `E1002` 는 **재시도로 풀리지 않습니다.**
  </Accordion>

  <Accordion title="초기화 자체가 실패한다" icon="triangle-exclamation">
    **볼 코드 —** `E1002` · `E1003` · `E2001` · `E2002` · `E5001` · `E5005`

    <Warning>
      **SDK `0.1.3` 이하는 현재 서버와 초기화되지 않습니다.** 서버가 내려주는 설정 자루에
      정수·불리언 값이 들어가면서 옛 판이 응답을 읽지 못합니다 —
      `0.1.4` 이상으로 올리세요. ([릴리즈 노트](/sdk/release-note/ios))
    </Warning>
  </Accordion>

  <Accordion title="콘솔에 데이터가 비어 있다" icon="database">
    **볼 코드 —** `E5001` · `E5006`

    좌표는 **300건 또는 60초** 단위로 올라갑니다 — 방금 걸은 동선이 바로 안 보여도 정상입니다.
    `await OneS1ght.send()` 로 앞당겨 확인하세요.

    앱을 강제 종료하면 미전송 좌표는 사라집니다(`E5006`, 인메모리 버퍼).
  </Accordion>
</AccordionGroup>

## 주의사항

<Warning>
  **로그 전송은 실패해도 앱을 막지 않습니다.** 로그는 부가 기능이라, 전송에 실패한 묶음은 재시도하지
  않고 버립니다. 좌표처럼 붙들고 재시도하면 진짜 데이터가 밀리기 때문입니다. 콘솔에 로그가 일부
  비어 있어도 측위 데이터는 정상일 수 있습니다.
</Warning>

<Warning>
  **에러는 즉시 올라가고, 나머지는 모아서 올라갑니다.** `ERROR` 는 앱이 죽기 전에 남겨야 원인을 알 수
  있어 바로 전송합니다. 정보 로그는 50건 또는 60초 기준으로 모입니다 — 콘솔에서 방금 찍은 정보 로그가
  안 보인다면 잠시 기다려 보세요.
</Warning>

<Warning>
  같은 코드가 쏟아지면 **오래된 것부터 버립니다**(기기당 2000줄 상한). 최근 상황이 진단에 더 쓸모
  있다는 판단입니다. 폭주 중인 문제를 볼 때는 처음이 아니라 **마지막** 줄을 보세요.
</Warning>

<Note>
  로그 보관 기간은 **30일**입니다. 측위 좌표(90일)보다 짧습니다 — 진단이 목적이라 그만큼 둘 이유가 없습니다.
</Note>

<Warning>
  콘솔의 로그 레벨 설정은 **아직 기기까지 내려가지 않습니다.** 지금은 앱이 남기는 로그를 콘솔에서
  조절할 수 없습니다.
</Warning>

## 문의할 때

[developers@onecheck.co.kr](mailto:developers@onecheck.co.kr) 로 아래를 함께 보내 주세요.
코드 하나만 있어도 확인 범위가 크게 좁혀집니다.

| 항목     | 예시                                       |
| ------ | ---------------------------------------- |
| 에러 코드  | `E3003`                                  |
| 발생 시각  | `2026-08-20 14:32` (시간대 포함)              |
| 기기·OS  | iPhone 15 Pro · iOS 27.1                 |
| SDK 버전 | `OneS1ght.sdkVersion`                    |
| 건물·층   | `building=B1 floor=9f3a1c2e`             |
| 프로필 ID | `pf_…` (있으면)                             |
| 로그 파일  | [로그 출력 방법](/sdk/faq/logging) 참고 (`.txt`) |

## 관련 문서

<CardGroup cols={2}>
  <Card title="에러 코드 안내" icon="triangle-exclamation" href="/sdk/faq/error-code">
    `E1001` \~ `E5006` 전체 목록과 조치.
  </Card>

  <Card title="로그 출력 방법" icon="file-lines" href="/sdk/faq/logging">
    Xcode · Console 앱으로 로그를 파일로 뽑기.
  </Card>

  <Card title="iOS 연동 가이드" icon="code" href="/sdk/integration/ios">
    초기화부터 측위 시작까지 전 과정.
  </Card>

  <Card title="코딩 에이전트 (MCP)" icon="robot" href="/sdk/mcp">
    에이전트에게 "E3003이 뭐야" 라고 물어보기.
  </Card>
</CardGroup>