Troubleshooting

Troubleshooting / 常见问题

Use this page for symptom-first checks. For exact install, build, flash, API, and configuration steps, follow the linked repository documents rather than a copied command from an old issue or chat.

Five-minute health check

1. Confirm there is only one active writer. Keep one continuous watcher. Stop match replay, interactive control, and old watcher processes before a live match.
2. Open the device status endpoint. Visit http://DEVICE-IP/api/status from the watcher computer. A successful JSON response separates a watcher/data problem from a device/LAN problem.
3. Read the watcher terminal. At startup it reports the detected mod, selected ESPN event, polling tier, and setup URLs. During operation, look for fetch failures, missing tickers, setup-sync failures, delivery retries, or device command failures.
4. Use the device IP if mDNS is uncertain. Phone, watcher, TTS service, and Stack-chan must be on the same trusted LAN. A DHCP reservation keeps the QR destination stable.
5. Do not reflash first. Save the watcher log and /api/status response, then use Debugging-and-recovery to identify the failing layer.

中文速查：先确认只有一个 watcher 在写设备，再从 watcher 电脑打开 http://设备IP/api/status。能返回 JSON，优先查 watcher 与数据源；打不开，优先查 设备、Wi-Fi、mDNS 与调试器连接。先留日志，不要一上来就刷机。

Stack-chan does not react

• /api/status is unreachable: try the numeric LAN IP. Check that the device and watcher are on the same network and that TCP port 80 is not being blocked locally. If an attached debugger also caused the screen and touch to stop, see “freezes or restarts” below.
• Status works, but the watcher logs stackchan commands failed or stackchan display failed: verify stackchan_host and HTTP transport in the active configuration. Serial transport does not support the phone setup relay or device status checks.
• Status and watcher are healthy, but there is no sound or movement: check the mute, tts, celebrating, and lastError fields in the status JSON. Indefinite mute survives a reboot. Use the Device API for the current control commands.
• Only the market or ticker is stale: look for Kalshi fetch failures, missing tickers, the current polling tier, and whether alerts are enabled for the selected market.

The device freezes, disappears from Wi-Fi, or restarts

• Detach xsbug and serial2xsbug during unattended operation. An exception breakpoint can pause the entire runtime, including Wi-Fi, touch, and timers; that can look like a crash without being a reboot. Use the Moddable xsbug-log headless logger when you need traces without breakpoint pauses.
• Make sure match replay and a second watcher are not sending commands at the same time. Multiple writers make ordering and retry behavior impossible to diagnose.
• Check the watcher for delivery retry queued, delivery dropped, feedback timeout, or TTS errors. Compare the installed components with the release notes before assuming that newer delivery ordering or retry behavior is present.
• If the device truly loses power, verify a stable USB supply and data cable. Capture the serial boot output before another reset so the reboot cause is not lost.
• Do not repeatedly retry a stalled mod installation. An interrupted install can leave the mod unavailable until it is installed again. Follow the recovery path in Getting started, using the instructions that match your checkout.

The setup page has no matches

The list includes a fixture only when the watcher can match both teams between an ESPN pre/in fixture and an open Kalshi event in the configured series.

• Confirm the watcher printed both setup URLs and did not report that its setup server failed.
• Check ESPN and Kalshi fetch warnings in the watcher terminal.
• Confirm kalshi_series_ticker, league, and look-ahead settings in the active configuration.
• Example market values are placeholders. Use a live Match Setup choice or the documented discovery workflow from Configuration.

The page stays on “waiting for watcher” / “等待 watcher”

The phone has written a pending request to the device, but the watcher has not acknowledged it.

• Confirm the continuous watcher is still running and using HTTP transport.
• Check for match setup apply failed and device match setup sync failed in its terminal.
• Verify the watcher can reach the device on TCP port 80 and can bind its local admin port.
• Avoid submitting several changes at once; the relay intentionally permits only one pending setup request.

Changing commentary style alone is hot-reloaded. It should not restart polling, replay old ESPN events, or reset the market baseline.

The QR code opens the wrong address

The QR image is generated before the mod is built; changing the URL shown as text does not rewrite the QR modules. Prefer a DHCP-reserved numeric IP or a hostname that every phone on the LAN can resolve, then regenerate and reinstall the mod using Getting started.

stackchan.local does not resolve

Use the numeric LAN IP to prove whether this is only mDNS. If that works, reserve the address in DHCP and use it for the static QR. VPNs, guest-network isolation, and some router/client combinations can prevent local hostname discovery.

There is no speech

1. Check for the MUTE / 静音 badge and inspect the mute field in /api/status. Long-pressing the top touch bar toggles the boss key.
2. Check the TTS service health from the device’s LAN, not only from localhost on the watcher computer.
3. Inspect the tts and lastError status fields and the computer firewall.
4. Confirm the configured TTS host is a LAN-reachable address.

Visual updates and the local tone fallback do not require dynamic TTS. If both speech and every visual reaction are absent, diagnose device delivery first.

Chinese text renders as boxes

Chinese glyphs require the optional host font resource. Apply the font workflow and rebuild the host as documented in Host firmware preparation (中文), then reinstall a compatible mod. This is not fixed by changing watcher language alone.

Markets show as missing

Sample tickers are not live forever. Confirm the selected event is still open, that the configured market belongs to it, and that Match Setup matched the selected position team. Only a confirmed tracks_position market uses holding language for price moves and suspected goals.

ESPN score or commentary appears late

The watcher reads the configured ESPN soccer summary endpoint, including its published commentary rows. The scoreboard, commentary, and ESPN web UI may update at different times.

• Confirm the watcher is in a live/full-speed polling tier and has no ESPN fetch backoff warning.
• Record when the event appeared upstream and when the watcher logged or spoke it, including timezone. This distinguishes upstream publication delay from polling or delivery delay.
• A market jump can trigger a suspected-goal alert first. It must remain explicitly unconfirmed until ESPN commentary provides confirmation.
• Unsupported or ambiguous commentary details are intentionally ignored rather than translated by guessing.

For a reproducible report, continue with Debugging-and-recovery.