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
Propose a change
Name Last commit message Last updated
page.json Remove internal identifiers from page.json 10d ago
README.md Condense README to fix-list + install + Files tab pointer 1mo ago
SKILL.md Add full SKILL.md to Files tab (frontmatter stripped) 1mo ago

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.