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

# Troubleshoot Stardeck Edge

> Diagnose Edge setup, connection, printer, cash-drawer, display, and update problems.

Start by connecting an HDMI display directly to the Edge machine, then restart the machine. The
screen shows local startup and connection logs, even when the machine cannot reach Stardeck.

Take a clear photo of the final error lines. They are usually more useful than a photo of the
dashboard's **Offline** badge.

<Tip>
  If the machine is showing `Stardeck-Setup-XXXX`, join it and open the setup page. Its
  **Diagnostics** panel provides another view of recent Edge, Wi-Fi, and update logs.
</Tip>

## Setup and pairing

<AccordionGroup>
  <Accordion title="The Stardeck-Setup network does not appear">
    Check that the Edge machine has power, then wait several minutes after startup.

    * A flashing green LED means it is waiting for first-time setup.
    * A paired machine with no network waits about 90 seconds before opening the setup network.
    * A machine that still has a local network connection does not enter Wi-Fi recovery just
      because the internet is down.

    Connect an HDMI display and restart the machine. Look for Wi-Fi, NetworkManager, or startup
    errors on the local screen.
  </Accordion>

  <Accordion title="The setup page does not open automatically">
    Stay connected to `Stardeck-Setup-XXXX`, open Safari or another browser, and go to
    `http://10.42.0.1`.

    The setup network intentionally has no internet. If the phone switches back to mobile data or
    another remembered Wi-Fi network, reconnect to `Stardeck-Setup-XXXX` and try again.
  </Accordion>

  <Accordion title="The pairing code expired or was rejected">
    Pairing codes are six digits and last 15 minutes.

    Return to **Settings → Edge Devices**, open the machine's pairing dialog, and
    select **New code**. Enter the new code on the setup page.

    Confirm that you are pairing the correct physical machine and have not created a duplicate
    machine record.
  </Accordion>

  <Accordion title="The machine joins Wi-Fi but pairing fails">
    Rejoin `Stardeck-Setup-XXXX` when it returns and read the error on the setup page.

    Common causes are:

    * a Wi-Fi network that requires a browser sign-in
    * blocked DNS or HTTPS access
    * an incorrect machine clock because NTP is blocked
    * outbound UDP port 123 being blocked

    If the error says the machine's date or clock is wrong, allow NTP and retry. Secure connections
    cannot work until the clock is correct.
  </Accordion>
</AccordionGroup>

## Network and offline machines

<AccordionGroup>
  <Accordion title="A paired machine is offline or flashing red">
    Check power, Ethernet, the router, and whether other devices at the location can reach the
    internet.

    If the Wi-Fi name or password changed, wait for `Stardeck-Setup-XXXX`, join it, and enter the
    new network details. Do not remove the machine or create a new pairing code; Wi-Fi recovery
    keeps its existing identity.

    If the local network works but the internet is down, the machine stays connected to the LAN
    and flashes red. Restore internet access rather than trying to re-pair it.
  </Accordion>

  <Accordion title="Forget & show hotspot was selected but the machine did not return">
    The dashboard loses contact as soon as the Edge machine leaves its old Wi-Fi. That is expected.

    Stand near the machine, wait for `Stardeck-Setup-XXXX`, and join it. If it does not appear,
    disconnect Ethernet, then restart the machine with an HDMI display attached and read the local
    network logs.
  </Accordion>

  <Accordion title="The machine is online but jobs do not arrive">
    Expand the machine in the dashboard and check each level:

    1. The machine shows **Online**.
    2. The peripheral has a green connection dot.
    3. The machine is granted to the app.
    4. The app's printer or screen alias is not marked broken.

    Send a hardware test from the Edge machine settings. If the test works, the remaining problem
    is in the app's grant, alias, or job flow.
  </Accordion>
</AccordionGroup>

## Printer and cash-drawer problems

<AccordionGroup>
  <Accordion title="A USB printer does not appear">
    Confirm the printer is powered on, contains paper, and uses a USB data cable. Reseat both ends,
    try another USB port, and wait a few seconds for discovery.

    If possible, test the cable with another computer. A power-only cable can turn on a device
    without carrying data.
  </Accordion>

  <Accordion title="The printer appears but Test is unavailable">
    Test is disabled when the Edge machine is offline, the printer is disconnected, or no driver
    has been saved.

    Make sure the machine is online, the printer has a green dot, choose **ESC/POS receipt
    printer**, and save before testing.
  </Accordion>

  <Accordion title="The receipt wraps badly or Thai text is garbled">
    Correct the paper width first: normally 48 characters for 80mm paper or 32 for 58mm.

    For mixed Thai and English, use **Image (Thai + Latin, any printer)**. For a printer with native
    Thai support, try **TIS-620** with code page 21, then 20 or 26.
  </Accordion>

  <Accordion title="The cash drawer does not open">
    Confirm the drawer is connected to the printer's drawer port and **Cash drawer attached** is
    enabled. Test pin 2, then pin 5.

    If neither works, confirm that the printer model can kick the drawer and that the cable matches
    the printer and drawer.
  </Accordion>
</AccordionGroup>

## Display problems

<AccordionGroup>
  <Accordion title="A connected HDMI display is not detected">
    Confirm the screen is powered on and set to the correct HDMI input. Reseat the cable, then try
    the other HDMI port.

    Refresh the Edge machine in the dashboard. A connected display should have a green dot.
  </Accordion>

  <Accordion title="The display is preparing for a long time">
    First-time kiosk preparation normally takes 5–15 minutes and needs working internet access.

    If it takes longer, check the HDMI log screen for package-download or disk errors. Restarting
    does not normally lose the saved display configuration.
  </Accordion>

  <Accordion title="The screen is blank or shows the wrong page">
    Check the display's content mode, URL, app, and path. For private apps, enable
    **Sign in automatically**.

    If the display is controlled live by an app, check that the machine is granted to that app and
    that its screen alias points to this display.
  </Accordion>

  <Accordion title="An update failed or rolled back">
    Leave the machine powered and online. A rollback means it protected itself by returning to the
    previous working release.

    If the status remains **Failed** or repeatedly rolls back, photograph the HDMI logs and contact
    support. Do not repeatedly unplug the machine during **Applying**.
  </Accordion>
</AccordionGroup>

## Contact support

Send [Stardeck support](mailto:support@stardeck.ai):

* the Edge machine name and serial number
* its dashboard status and **Last seen** time
* the LED behavior
* a photo of the HDMI logs or setup-page Diagnostics panel
* what changed immediately before the problem

Do not send Wi-Fi passwords, device credentials, or an active pairing code.