Skip to content

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:

  1. 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).
  2. Check the log panel at the bottom of the dashboard for the most recent errors.
  3. Check the constraint snapshots — most “task didn’t run” issues with automation running resolve to a failing constraint.
  4. Check the hub indicator in the status bar — if the hub connection is degraded, snapshot freshness on the website is your symptom.
  5. If the backend won’t start or comes up without your settings, see Unreadable config.

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.


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:

  1. Keeps a copy next to it, skynode_config.json.corrupt-<timestamp>.json.
  2. Tries to recover by dropping only the cached hardware graph (it re-syncs from the hub), keeping the binding, device configs and install_id.
  3. 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.

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.

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.

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.

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’s offline, the SkyNode process died or the broker thinks it did (keep-alive failure).

See Unreadable config. If that’s not it, the fastest stable diagnosis is to:

  1. Look at the most recent backend log in %LOCALAPPDATA%\SkyNode\logs.
  2. Try starting with a known-good config (restore the preserved copy, or point SKY_NODE_CONFIG_PATH at another file).
  3. 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.

  • Log files — %LOCALAPPDATA%\SkyNode\logs on Windows; the log panel in the GUI streams the same log live.
  • Telescope log book on the hub — TelescopeLogEntry records 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.