skill

Octolux App Server — debug startup and runtime failures

Public Unreviewed

by Caleb

Diagnose any Octolux Node.js app server failure that breaks the Dashboard (startup or runtime). Six symptoms with root causes and fixes.

Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
skill / octolux-app-server-debug

Install

Diagnose any Octolux Node.js app server failure that breaks the Dashboard. Six symptoms: ECONNREFUSED 0.0.0.0:8830 from missing ws npm dep, EADDRINUSE port-in-use, silent crash after start, blank-despite-healthy, dashboard section-button first-click-invisible-tab fix, and section-button-every-click-fails (Hydrogen 409 silently dropped by the cli() wrapper). Includes the Adom HTTPS proxy 5xx-body-stripping gotcha forcing HTTP 200 with {ok:false}.

adom-wiki pkg install caleb/octolux-app-server-debug

Latest: v0.1.4, published

Contents

What this skill fixes

Six failure modes on the Octolux Node.js app server, with a known root cause and a repeatable fix in this skill. Cross off as the upstream code ships a fix.

  • Dashboard webview blank on a fresh container — ECONNREFUSED 0.0.0.0:8830, octolux health says "not running", server log shows ERR_MODULE_NOT_FOUND: 'ws' (or any npm dep). Cause: npm install was never run in ~/ntx-embedded/apps/octolux/.
  • Port already in use — EADDRINUSE 0.0.0.0:8830 (stale node server.js).
  • Server healthy but dashboard webview blank — octolux health OK, port bound, iframe empty.
  • Server starts then dies silently — exits a few seconds after launch.
  • Section button (VNC / Deploy / …) does nothing on the first click — works on subsequent clicks. Cause: server creates the tab behind the dashboard.
  • Section button does nothing on every click — server returns {"ok":true,"action":"created"} but no tab. Underlying: 409 No browser session is connected, error code: 502 no-body from Adom proxy. Cause: the server's cli() wrapper silently drops subprocess errors.

Install

adompkg install caleb/octolux-app-server-debug
# or the whole NTX bundle:
adompkg install caleb/ntx-octolux-toolkit

Lands at ~/.claude/skills/octolux-app-server-debug/ and becomes discoverable to Claude on the next run.

Full reference

Browse SKILL.md in the Files tab — symptom diagnostics, code excerpts of the fixes, "do not do these" rules, prevention guidance.