HKUDS/DeepTutor · error · SystemExit

DeepTutor Web assets are not installed. Install the full app

Error message

DeepTutor Web assets are not installed. Install the full app with `pip install -U deeptutor`, or run from a source checkout that contains `web/`.

What it means

Raised by _resolve_frontend when neither packaged web assets nor a source web/ directory exists, so there is no frontend to launch at all. The launcher exhausted all frontend runtime options (packaged assets, standalone build, source checkout).

Source

Thrown at deeptutor/runtime/launcher.py:776

            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`, "
        "or run from a source checkout that contains `web/`."
    )


def _coerce_pid(value: object) -> int | None:
    if isinstance(value, bool) or not isinstance(value, int | str):
        return None
    try:
        pid = int(value)
    except (TypeError, ValueError):
        return None
    return pid if pid > 0 else None


def _coerce_port(value: object) -> int | None:
    if isinstance(value, bool) or not isinstance(value, int | str):
        return None

View on GitHub (pinned to 3e82f13042)

Solutions

1. Install the full app: `pip install -U deeptutor` (includes packaged web assets)
2. If you intend to run from source, ensure the repo's web/ directory exists at the project root
3. If you only need the API/CLI, use `deeptutor serve` instead of `deeptutor start`

Example fix

# before
pip install deeptutor-cli
deeptutor start   # SystemExit
# after
pip install -U deeptutor
deeptutor start

import importlib.util, pathlib
pkg = importlib.util.find_spec("deeptutor")
root = pathlib.Path(pkg.origin).parent
has_web = (root / "web").is_dir()
has_assets = (root / "web" / ".assets").exists() or (root / "web_static").exists()
if not (has_web or has_assets):
    raise SystemExit("Install full app: pip install -U deeptutor")

When it happens

Trigger: Running deeptutor start from a CLI-only install (pip install deeptutor-cli) or a source checkout where the web/ folder is missing/deleted, so no FrontendRuntime can be constructed.

Common situations: Installing the lightweight `deeptutor-cli` package (no web assets) and then running `deeptutor start`; cloning the repo without submodules or after deleting web/; corrupted wheel install missing the packaged assets directory.

Related errors

• GraphRAG is not installed. Run `pip install 'deeptutor[graph
• LightRAG is not installed. Run `pip install 'deeptutor[rag-l
• AnimationGenerator requires the optional math-animator extra
• Node.js 20+ is required to run the source production build.
• start.frontend_restart_failed

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