HKUDS/DeepTutor · error · SystemExit

Node.js 20+ is required to run the source production build.

Error message

Node.js 20+ is required to run the source production build.

What it means

Raised by _resolve_frontend in deeptutor/runtime/launcher.py when running a source install (web/ checkout present) in production (non-dev) mode but no Node.js executable was found on PATH. The launcher needs Node 20+ to build the frontend production bundle via npm.

Source

Thrown at deeptutor/runtime/launcher.py:759

        runtime_web = _copy_packaged_web_if_needed(
            packaged,
            home=home,
            api_base=api_base,
            auth_enabled=auth_enabled,
        )
        return FrontendRuntime("packaged", [node, str(runtime_web / "server.js")], runtime_web)

    source = _source_web_dir(home)
    if source is not None:
        npm = shutil.which("npm")
        if not npm:
            raise SystemExit(
                "npm not found. Source installs require Node.js/npm and `cd web && npm install`."
            )
        _ensure_web_dependencies(source, npm)
        if not dev:
            if not node:
                raise SystemExit("Node.js 20+ is required to run the source production build.")
            _ensure_source_production_build(
                source,
                npm,
                api_base=api_base,
                auth_enabled=auth_enabled,
            )
            standalone = source / SOURCE_PRODUCTION_DIST_DIR / "standalone"
            return FrontendRuntime(
                "source-production",
                [node, str(standalone / "server.js")],
                standalone,
            )
        return FrontendRuntime(
            "source", [npm, "run", "dev", "--", "--port", str(frontend_port)], source
        )

    raise SystemExit(
        "DeepTutor Web assets are not installed. Install the full app with `pip install -U deeptutor`, "

View on GitHub (pinned to 3e82f13042)

Solutions

1. Install Node.js 20+ (e.g. via nvm: `nvm install 20 && nvm use 20`) and ensure `node` is on PATH before running deeptutor
2. Run in dev mode: `deeptutor start --dev` (or start(dev=True)) which skips the production build
3. Install the full packaged app instead: `pip install -U deeptutor` which ships prebuilt web assets and needs no Node

Example fix

# before
deeptutor start   # from source checkout, no node on PATH
# after
nvm use 20 && deeptutor start
# or
deeptutor start --dev

import shutil
node = shutil.which("node")
if not node:
    raise SystemExit("Install Node.js 20+ first")
import subprocess
v = subprocess.run([node, "--version"], capture_output=True, text=True).stdout
major = int(v.strip().lstrip("v").split(".")[0])
assert major >= 20, f"Node 20+ required, got {v}"

When it happens

Trigger: Calling deeptutor start (or launcher.start()) from a source checkout without dev=True on a machine where `node` is not on PATH or is not version 20+.

Common situations: Running from a git clone in a minimal container/venv where Node was never installed; Node installed via nvm but the shell launching deeptutor doesn't source nvm; CI images without Node.

Related errors

• start.frontend_restart_failed
• CodeGeneratorAgent generation prompts are not configured.
• SummaryAgent prompts are not configured.
• GraphRAG is not installed. Run `pip install 'deeptutor[graph
• LightRAG is not installed. Run `pip install 'deeptutor[rag-l

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/23a0133f363feed7. Report an issue: GitHub.