Troubleshooting
This page is a starting point when something’s wrong with a SkyNode install. It covers the subsystems that produce useful diagnostic signal, what happens when the config file can’t be read, and a handful of recurring failure modes.
If you’re hitting something not listed here, the fastest path to a diagnosis is usually:
- Check the automation state and its reason in the top status bar — click the reason for what it means and where to fix it (automation not started, MANUAL control, a lease, an interlock, a failing constraint, the hub unreachable).
- Check the log panel at the bottom of the dashboard for the most recent errors.
- Check the constraint snapshots — most “task didn’t run” issues with automation running resolve to a failing constraint.
- Check the hub indicator in the status bar — if the hub connection is degraded, snapshot freshness on the website is your symptom.
- If the backend won’t start or comes up without your settings, see Unreadable config.
Subsystems to know
Section titled “Subsystems to know”A few SkyNode modules are particularly useful when diagnosing:
| Module | Useful for |
|---|---|
sync_monitor |
Compares the local hardware graph with the hub’s every 20 seconds, applies safe differences live, and logs the ones that need a restart |
connection_manager |
Owns the HTTPS / WS connection to the hub; surfaces transport-level errors |
token_manager |
Manages access + refresh tokens; logs token-refresh failures |
hub_publisher |
Publishes snapshots and events to the hub; backlog growth here means upstream is unhealthy |
device_manager |
Owns device lifecycle; surfaces driver-init errors |
resource_manager |
Health/thermal/battery/storage state for the host and devices |
crash_reporting |
Sends unhandled errors to Skynet’s error tracker (GlitchTip) when the build is configured for it, with credentials scrubbed; it writes nothing to disk |
logging_setup |
Configures the log layout; check here if you need a different log destination or verbosity |
The dashboard surfaces summarized state from most of these in real time; the underlying log file has the detail.
Unreadable config
Section titled “Unreadable config”There is no separate recovery flow after an unclean shutdown: on every start SkyNode checks its credentials and config and goes to the dashboard, or to sign-in and node selection when the install has no valid hub credentials or binding. A node whose automation was started resumes it, and devices whose auto-connect is armed reconnect on their own.
If the config file can’t be read — usually after an update changed the schema — SkyNode:
- Keeps a copy next to it,
skynode_config.json.corrupt-<timestamp>.json. - Tries to recover by dropping only the cached hardware graph (it re-syncs from the hub), keeping the binding, device configs and
install_id. - If that also fails, runs on defaults without overwriting your file and shows a banner on every page until the config loads again. Don’t edit settings while the banner is up: fix or roll back the build, or restore the preserved copy.
Common failure modes
Section titled “Common failure modes”Hub connection looks fine but tasks don’t run
Section titled “Hub connection looks fine but tasks don’t run”First check that automation is started and not blocked (top status bar). With automation running, it is almost always a constraint failure: look at the constraint actions on the Overview and at Settings → Operational Constraints for any in a non-OK state. The most common culprits:
- Weather constraint still tripped after weather clears — a constraint waits for its readings to stay in range for its stability period before it reads safe again, and a stale reading (older than the driver’s stale threshold) doesn’t count.
- Sun altitude constraint — observing window hasn’t opened yet (or has closed).
- Storage / battery constraint — host disk filled up, or battery on a portable rig dropped below threshold.
- MountSunSeparation constraint — the mount happens to be parked near the sun’s current position and the constraint is keeping it put.
When the readings are back in range and you judge it safe, you can skip that stability wait from the constraint’s actions on the Overview. The override is local to this installation, and the next out-of-range reading trips the constraint again; it does not clear a constraint whose readings are still out of range.
Hardware graph looks stale
Section titled “Hardware graph looks stale”If the website shows configuration changes you’ve made but the SkyNode local GUI doesn’t — or vice versa — the hardware graph cache in SkyNodeConfig is stale.
- Check the hub indicator in the status bar (hover it for the sync state and the last error).
- Check the sync monitor’s log lines for failed pulls and for changes it reports as needing a restart; restart SkyNode to apply those.
Devices keep dropping offline
Section titled “Devices keep dropping offline”Driver-level. The log viewer is your friend; filter to the affected device. Common patterns:
- ASCOM driver: the COM proxy is dying, often because the underlying ASCOM driver app crashed or was force-quit. Restarting the ASCOM driver host usually fixes it. If the COM ProgID has changed, update the driver config.
- Serial / TCP driver: the connection string is wrong or the device endpoint moved. Reconnect from the device editor; verify cabling.
- Vendor software driver (MaxIm DL, Boltwood Clarity, etc.): the vendor application is in a bad state. Restart it before restarting SkyNode.
Tasks complete but don’t appear on the hub
Section titled “Tasks complete but don’t appear on the hub”File upload back-pressure. Check the Files page for frames stuck before or in transfer, and the log for upload errors. Common causes:
- Installation credentials lost — the install’s refresh token expired or was revoked (pairing another install to the same telescope does this). A banner at the top of the dashboard says so; sign in and pair the install again.
- Network failure — site connectivity is down. Tasks complete locally but results queue until the hub is reachable again.
MQTT subscribers see stale data
Section titled “MQTT subscribers see stale data”If local MQTT consumers (status displays, monitoring tools) report stale state:
- Check
local_broker.enabled— easy to leave off after a config edit. - Check that the MQTT broker process is up.
- Confirm the LWT topic still shows the SkyNode install as
online— if it’soffline, the SkyNode process died or the broker thinks it did (keep-alive failure).
Backend won’t start at all
Section titled “Backend won’t start at all”See Unreadable config. If that’s not it, the fastest stable diagnosis is to:
- Look at the most recent backend log in
%LOCALAPPDATA%\SkyNode\logs. - Try starting with a known-good config (restore the preserved copy, or point
SKY_NODE_CONFIG_PATHat another file). - As a last resort, unbind and re-pair the install (Settings → General → Unbind installation). The hub creates a new installation record; the local
install_id, and so the MQTT topics, stay the same. Every device has to be connected once again and automation started again.
Where to get help
Section titled “Where to get help”- Log files —
%LOCALAPPDATA%\SkyNode\logson Windows; the log panel in the GUI streams the same log live. - Telescope log book on the hub —
TelescopeLogEntryrecords capture significant events (manual takeovers, shutdowns, device failures) and are persisted to the hub even when the local logs rotate away.
If you’ve checked all of the above and you still don’t know what’s wrong, capture a recent log slice and the build identifier (Settings → General → About) and flag it to the Skynet ops team.