> ## 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.

# Troubleshooting

> How to find the cause and fix it, symptom by symptom, when positioning does not work. Working down the list in order resolves most cases.

Find your symptom first, then **work through that item's checks from the top down**.
They are ordered from the most common cause.

## Quick diagnosis

| Symptom                                                  | Go to                                                                                                                   |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| No floor plan at all in the app                          | [No floor plan appears in the app](#no-floor-plan-appears-in-the-app)                                                   |
| The floor plan appears but there is no position dot      | [No position dot appears in the app](#no-position-dot-appears-in-the-app)                                               |
| The dot appears but sits in the wrong place              | [Position is shown somewhere other than reality](#position-is-shown-somewhere-other-than-reality)                       |
| The dot keeps moving while you stand still               | [Position jitters or jumps badly](#position-jitters-or-jumps-badly)                                                     |
| You walk 10 m but the screen shows 5 m                   | [Distance travelled does not match reality](#distance-travelled-does-not-match-reality)                                 |
| No event fires when you enter a zone                     | [Zone events do not fire](#zone-events-do-not-fire)                                                                     |
| The anchor LED is red                                    | [Anchor LED is red](#anchor-led-is-red)                                                                                 |
| Apply to devices fails / an anchor shows as disconnected | [Apply to devices fails or an anchor shows as disconnected](#apply-to-devices-fails-or-an-anchor-shows-as-disconnected) |
| The console only shows the sample floor plan             | [The console stays in simulation mode](#the-console-stays-in-simulation-mode)                                           |

***

## No floor plan appears in the app

You open the app and the floor plan is empty, or it keeps loading.

<Note>
  **If you are using the verification app (handed over by your contact)**, the key is embedded in the app — skip
  items 1 and 2 (key checks) and start at item 3 (network). The key checks only apply if you are developing your own app.
</Note>

<Steps>
  <Step title="Check that the SDK key is correct">
    Check that the key you put in the app starts with `ock_sdk_` and that no whitespace slipped in at either end.
    Copy and paste often drags along a space or a line break.

    → [Mobile SDK keys](/en/locator/sdk-keys)
  </Step>

  <Step title="Check that the temporary geospaceKey value is correct">
    The app currently fetches floor plan and anchor information with this temporary value. If the value your contact
    gave you is missing or wrong, the floor plan does not load — check the value and the whitespace around it.

    → [Installation · Prepare your key](/en/sdk/quick-start)
  </Step>

  <Step title="Check the network">
    The floor plan is downloaded from the server. If the venue Wi-Fi blocks outbound access, it will not load.
    Switch to cellular data and try again.
  </Step>

  <Step title="Check that a floor plan is saved for that floor">
    If the floor is marked **incomplete** in the GeoSpace floor list, no floor plan has been saved for it.

    → [Building · floor plan registration](/en/geospace/spaces)
  </Step>
</Steps>

***

## No position dot appears in the app

The floor plan renders fine, but only your position dot is missing.
**Positioning has not started at all**, and the cause is almost always one of the five below.

<Note>
  If you are using the verification app (key embedded), item 3 (initialization code) does not apply — check items 1 and 2, then jump to 4 and 5.
</Note>

<Steps>
  <Step title="Check that the device supports UWB">
    **iPhone 11 and earlier have no UWB chip, so positioning does not work.**
    Confirm the device is iPhone 12 or later on iOS 27.0 or later.

    <Note>
      On devices without UWB support the app still runs normally and only positioning is disabled.
      So the dot can simply be missing, quietly, with no error message.
    </Note>
  </Step>

  <Step title="Check app permissions">
    In iOS Settings → the app, check that **Location** and **Nearby Interaction** permissions
    are granted. If either one is denied, UWB positioning does not start.
  </Step>

  <Step title="Check that you initialized with the temporary geospaceKey value">
    Initializing the SDK without `geospaceKey` **disables positioning without raising an error** —
    the classic cause of a working floor plan and zones but no dot.

    ```swift theme={null}
    try await OneS1ghtSDK.initialize(sdkKey: "ock_sdk_...",
                                     geospaceKey: "<value from your contact>")  // ← is this argument present?
    ```

    → This is not a key you issue yourself — **your contact hands it over with the demo kit**. See [Installation · Prepare your key](/en/sdk/quick-start).
  </Step>

  <Step title="Check that the cluster was applied">
    In GeoSpace **Floor Plan Placement · Wireless Design**, confirm you finished through the third stage, Cluster,
    and pressed **\[Save] → \[Apply to devices] → \[Done]**.

    <Note>
      Demo kits are sometimes **shipped with the cluster settings already loaded** — positioning can work
      even when Apply to devices did not complete, so make the final call on **whether the dot appears in the app**.
      → [Apply to devices fails or an anchor shows as disconnected](#apply-to-devices-fails-or-an-anchor-shows-as-disconnected)
    </Note>

    <Warning>
      The master anchor and the session ID **must not be set arbitrarily.**
      Enter exactly the values OneS1ght gave you.
      If you did not receive them, contact `onesight-support@onecheck.co.kr`.
    </Warning>
  </Step>

  <Step title="Check anchor power and your position">
    Check that all 4 anchors have power, and that where you are standing is
    **inside the rectangle the 4 anchors form**. Outside that area no position is produced.
  </Step>
</Steps>

***

## Position is shown somewhere other than reality

The dot appears, but not where you are actually standing.
**If everything is shifted consistently in one direction**, a coordinate origin problem is by far the most likely cause.

<Steps>
  <Step title="Check that you applied the floor plan image offset">
    This is the most common cause. The coordinate origin on the placement screen is
    **the (0, 0) of the whole uploaded floor plan image, not the corner of the room**.

    If the image includes margins or exterior walls, you must add that much to your values.
    For example, if the bottom-left corner of the room is (0.6, 1.5) away from the image origin,
    an anchor you measured as (0, 0) on site must be entered as `(0.6, 1.5)`.

    <Tip>
      **Measuring the shift distance and direction makes the correction easy.** If you entered all 4 anchors wrong in the same way,
      the dot is shifted by the same distance in the same direction, so **moving every anchor coordinate the same distance in the opposite direction** fixes it.
      When the offset is missing, the dot shifts **towards the floor plan origin (bottom-left)**.
      (The floor plan may look rotated in the app, so judge direction **against the floor plan**, not against the screen.)
    </Tip>
  </Step>

  <Step title="Check that you did not swap X and Y">
    If the dot looks flipped along the diagonal, X and Y have been swapped.
    The horizontal direction is X and the vertical direction is Y.
  </Step>

  <Step title="Compare the coordinates anchor by anchor">
    Stand directly under each anchor and check where the dot lands.
    If it is off **only at one corner**, only that one anchor's coordinates were entered wrong.
  </Step>

  <Step title="Check that you did not place by dragging alone">
    Dragging and dropping on the floor plan leaves your eyeballed error in place.
    In the 'Placed' list you must **type in the values you measured on site as numbers**.

    → [Floor plan placement](/en/geospace/placement#1-floor-plan-placement)
  </Step>
</Steps>

***

## Position jitters or jumps badly

The dot keeps trembling while you stand still, or suddenly jumps far away.
This is most likely an **installation environment problem**.

<Steps>
  <Step title="Check for metal near the anchors">
    Metal such as steel, iron and aluminium interferes with radio signals.
    If an anchor sits near metal shelving, a steel column, refrigeration equipment or a metal partition, move it.
  </Step>

  <Step title="Check the mounting height">
    The recommended height is **2.4 – 3 m**, and **closer to 3 m is better**. It must be at least 2 m.
    At a low height — resting on a desk, say — people's bodies block the signal and positioning becomes unstable.
  </Step>

  <Step title="Check the anchor layout">
    If the anchors are bunched on one side or nearly in a straight line, the error grows sharply.
    Check that they are placed at the four corners of a **rectangle that surrounds the coverage area**.
  </Step>

  <Step title="Check the number of anchors">
    Stable positioning is not possible with fewer than 4.
    Check whether one has lost power and the system is running on 3.
  </Step>

  <Step title="Check whether you are at the edge of the measured area">
    Accuracy drops the further you go outside the rectangle.
    If it only jitters at the edges that may be normal, so check again from the centre.
  </Step>
</Steps>

***

## Distance travelled does not match reality

You walk 10 m but the screen shows only 5 m of movement.
The **floor plan scale** is wrong.

<Steps>
  <Step title="Check the scale setting again">
    In GeoSpace **Floor Plan Placement**, run **\[Set scale from two points]** again.
    The span you pick with the two points and the real distance you enter must be **exactly the same span**.

    → [Configure the plan (scale)](/en/geospace/spaces#3-configure-the-plan-scale)
  </Step>

  <Step title="Check that the measured span is long enough">
    The scale is calculated as **the real distance you enter ÷ the distance between the two points you picked on the plan**.
    But clicking an exact spot with a mouse is hard, so you are off by a few pixels every time,
    and **that error is about the same whether the span is short or long.** So the shorter the span, the larger the error in proportional terms.

    Say your click is off by 3 pixels —

    | Span picked                       | Error ratio | Scaled to a 12 m store |
    | --------------------------------- | ----------- | ---------------------- |
    | 1 m (about 30 pixels on screen)   | 10 %        | **1.2 m off**          |
    | 12 m (about 360 pixels on screen) | 0.8 %       | 10 cm off              |

    The same slip disappears into the noise if you pick a long span —
    pick again using **the longest span on the floor plan (wall to wall)**.
  </Step>

  <Step title="Check that the unit is metres">
    The real distance you enter is in **metres (m)**. Entering centimetres puts you off by a factor of 100.
  </Step>
</Steps>

<Note>
  Changing the scale changes the entire floor plan coordinate system.
  **After resetting the scale, check the anchor coordinates again.**
</Note>

***

## Zone events do not fire

Position is produced normally, but entering a zone produces no enter event.

<Steps>
  <Step title="Check that the zone is actually drawn">
    In the OneS1ght console under **Space management**, check that a zone is saved on that floor.

    → [Space management](/en/locator/areas)
  </Step>

  <Step title="Check that the zone is inside the positioning area">
    A zone drawn **outside** the rectangle the 4 anchors form gets no position, so no event fires either.
  </Step>

  <Step title="Check that the zone is not too small">
    Positioning has error. If a zone is too narrow, the dot crosses in and out,
    firing enter and exit repeatedly — or never being detected at all.
  </Step>
</Steps>

***

## Anchor LED is red

The LED on the front of the anchor is **lit red**. The anchor has not attached to the GeoSpace management channel (Wi-Fi).

<Note>
  **Positioning itself can still work** when the LED is red — this network is the management channel GeoSpace uses to push settings down,
  which is separate from positioning, where the anchor emits signals. If the dot shows up in the verification app, positioning is fine.
</Note>

**Reference — manufacturer LED definitions** (use these when reporting status to support)

| LED                                                | Manufacturer definition    |
| -------------------------------------------------- | -------------------------- |
| Yellow on                                          | Power normal               |
| Green on                                           | Wireless network connected |
| Green blinking + blue on / red blinking + green on | Receiving UWB signal       |
| Red on                                             | Wireless network error     |

<small>Source: Geoplan AN-500 product specification (2025)</small>

<Steps>
  <Step title="Check the venue Wi-Fi">
    The anchor reaches the server over the **venue Wi-Fi (2.4 GHz)**. Check that the router is on, that the internet works,
    and that the Wi-Fi password has not changed.
  </Step>

  <Step title="Power cycle it">
    Unplug the USB-C and plug it back in to reboot. Watch for 1–2 minutes to see whether the red clears.
  </Step>

  <Step title="Check the adapter rating">
    Check that the adapter is **5 V / 3 A**. An underpowered adapter (1 A, for example) causes unstable boot and communication.
  </Step>

  <Step title="If it is still red">
    The anchor's Wi-Fi settings may need to be configured again — send the anchor S/N and LED status
    to `onesight-support@onecheck.co.kr`.
  </Step>
</Steps>

***

## Apply to devices fails or an anchor shows as disconnected

An anchor shows as **disconnected (grey) in the connection list** of the step 5 cluster, or **\[Apply to devices]** does not complete.

<Note>
  **In most cases you can just continue.** The anchor only **emits** positioning signals, so it does not need to stay attached to the server,
  and demo kits are sometimes shipped with the cluster settings already loaded.
  Regardless of what the connection list shows, go through **\[Apply to devices anyway] → \[Done]**,
  then decide based on **whether the dot appears in the app** in [step 7 verification](/en/geospace/verify).
</Note>

<Steps>
  <Step title="Check that all 4 anchors have power">
    If the LED is lit, power is fine. Only for anchors that are off, check the cable and the power strip.
  </Step>

  <Step title="Go through to [Done] and move on to verification">
    Even if a warning appears, press **\[Apply to devices anyway] → \[Done]** and move to step 7.
    There is nothing more you can confirm by staying on this screen.
  </Step>

  <Step title="If the dot still does not appear during verification, contact support">
    Send **the anchor S/N · LED status · a screenshot of the connection list** to `onesight-support@onecheck.co.kr`.
  </Step>
</Steps>

***

## The console stays in simulation mode

The **Not connected — simulation mode** badge on the **Settings → Geospace integration** card does not go away.

<Steps>
  <Step title="Check that the partner key is registered">
    **Issuing** a key in GeoSpace and **registering** it in the OneS1ght console are two different things.
    The most common case is issuing it and never registering it.

    → [6. Positioning connection · key issuance](/en/geospace/connect#2-register-it-in-the-ones1ght-console)
  </Step>

  <Step title="Check the key format">
    The partner key starts with `gpk_`. Do not confuse it with the SDK key (`ock_sdk_`). They are different keys.
  </Step>

  <Step title="Check that you pressed [Save]">
    Entering the key without pressing **\[Save]** changes nothing. Before saving, you can use **\[Test connection]** to check that the key is valid.
  </Step>

  <Step title="Check permissions">
    Only **Manager and above** can open and edit this screen.
    A viewer account cannot register the key.
  </Step>

  <Step title="Check the network">
    The console server must be able to make outbound calls to the GeoSpace server.
    If your corporate network blocks it, check the allowed-host configuration.
  </Step>
</Steps>

***

## Still not resolved

Contact `onesight-support@onecheck.co.kr`.
**Sending the following information along with your question makes this much faster to diagnose.**

| Item                      | Example                                                             |
| ------------------------- | ------------------------------------------------------------------- |
| Symptom                   | "The dot appears but is always shifted 2 m to the right"            |
| Site                      | Building and floor name, measured size of the space                 |
| Anchor coordinates        | Screenshot of the 'Placed' list                                     |
| Console connection status | Screenshot of the badge on the Settings → Geospace integration card |
| Test device               | iPhone 15 Pro / iOS 27.1                                            |
| App screen                | Screenshot showing the position dot (or the lack of one)            |