Troubleshooting
Find your symptom in the tables below; each row gives the check and the fix. Before asking for help, note
the revision (git rev-parse HEAD), your assistant and its version, node --version, pnpm --version,
the command that fails, and, if the server starts, the output of get_server_info. Share a minimal error
message without keys, personal data or private lesson content.
Install and build
| Symptom | Check and fix |
|---|---|
Repository not found when cloning |
check the address, https://github.com/HolobiomicsLab/studium.git: the repository is public and asks for no login |
pnpm not found or too old |
corepack enable, or install pnpm 9.15.9 |
ERR_MODULE_NOT_FOUND or a missing dist/ |
rerun ./setup.sh, or pnpm install --frozen-lockfile, pnpm build:libs, then pnpm --filter studium-vscode build |
tsx not found |
start the built server with node apps/studium-vscode/dist/lesson-mcp.cjs instead |
listen EPERM from tsx inside a sandbox |
run through the loader, which opens no IPC socket: node --import apps/lesson-mcp/node_modules/tsx/dist/loader.mjs apps/lesson-mcp/src/session-runner-cli.ts … |
ModuleNotFoundError in Python |
use the repository's .venv and .venv/bin/pip install -r requirements.txt, not the system Python |
Connecting an assistant
| Symptom | Check and fix |
|---|---|
| The server waits and shows no page | normal: it talks over stdio to an MCP client, not to a browser |
| No Studium tools in the chat | read the client's MCP log, check the absolute path to lesson-mcp.cjs, restart the server and open a new conversation |
| VS Code ignores the JSON | .vscode/mcp.json uses servers; Claude Code and Cursor use mcpServers; OpenCode v2 uses mcp.servers |
Codex: MCP tool call requires approval, but approval policy is never |
answer the prompts interactively, or run codex exec --approve-for-me |
| A tool you read about is missing | the build predates your checkout: rebuild with pnpm --filter studium-vscode build, restart the server, compare get_server_info.build |
persistence.durable is false |
STUDIUM_EPHEMERAL=1 is set and STUDIUM_DATA_DIR is not: progress is lost at restart |
| The lesson you asked for is not found | the server looks in BUNDLES_ROOT first, then ~/.studium/library; ask the assistant to call list_lessons |
| Two different steps in the chat and the pane | they run two servers; drive the lesson from one of them only |
During a lesson
| Symptom | Check and fix |
|---|---|
| Answer rejected | send the learner's words with submit_response {kind: "reply", text}; read get_operator_context for the expected format |
| A quiz choice id is refused | choices are reshuffled per session: use the id shown in the current step, never one remembered from another session |
run required: call get_run_manifest, run it, then submit_run_result |
the step needs a real run: follow get_run_manifest, run the capsule, then submit_run_result |
| Open answers say "check it yourself" | expected without a judge model; see Configuration |
| The assistant answers or rates for you | stop it and answer yourself; the server instructions forbid it, and self-rating never moves mastery |
session not found: … |
the server restarted or the session was closed; the message says how to resume: start_lesson_session with the same bundle_ref and learner_id, or start_review_session with the same learner_id; the MCP Apps panel, the Claude Code pane and the VS Code pane show a "Session lost" notice with a reopen control instead of the stale scene |
| A self-rating is refused as expired | the request was lost by an older server; answer the step again to be asked anew |
now_ms must be an integer epoch in milliseconds … |
pass a whole number of milliseconds since 1970, or leave now_ms out to use the server clock |
create_lesson refuses the course_id |
a lesson of that id already exists: under BUNDLES_ROOT it is never replaced, so choose another id; in your library, pass overwrite: true to replace a self-study lesson no teacher validated |
VS Code
| Symptom | Check and fix |
|---|---|
| F5 finds no launch configuration | open the folder apps/studium-vscode, which holds the Extension Host configuration |
| The installed VSIX finds no lesson | lessons are not in the VSIX: put them in ~/.studium/library, or set studium.bundlesRoot and studium.bundleRef, or use Studium: Pick a course |
A vscode:// link opens nothing |
the path must be absolute, without .., percent-encoded, to an existing .json file |
| Equations or plots look degraded | run pnpm --filter studium-vscode vendor, rebuild, and keep studium.assets at vendor |
| No review count in the status bar | none is due, or you have no history yet; use the refresh button of the Lessons view |
HTTP API
| Answer | Meaning | What to do |
|---|---|---|
400 |
invalid JSON or schema, missing request_id or expected_scene_id |
fix the request from api:call operations |
401 / 403 |
wrong token, a browser Origin, or a non-local address |
give the server and the client the same token through their environment |
404 |
unknown operation, or session gone (forgotten or server restarted) | do not invent a resume; start again from durable state |
409 stale_scene |
the step changed | read get_operator_context, then ask the learner again |
409 request_conflict |
a request_id reused for a different request |
inspect the earlier action before choosing a new id |
410 forgotten |
the session was erased | respect the erasure |
413 / 415 |
body over 1 MiB, or not application/json |
send JSON; pass media as references |
422 |
the engine refused the operation | read the error; do not force progress |
503 |
busy, or the receipt limit (512 mutations or 16 MiB) is reached | retry with the same request_id if busy; export, then restart the server if full |
After a network error, resend the same file with the same request_id, never a second answer.
Teacher tools and services
| Symptom | Check and fix |
|---|---|
check refuses the draft |
compare schema, ids and quotes with the evidence; keep status: draft and validated_by: null |
| Output folder already exists | choose a new path; the tools keep existing outputs on purpose |
| Observatory or MySTRA shows 404 | check --course-root and the course subfolder; see Observatory |
Planner answers 503 |
no model is configured; set one, or use STUDIUM_LLM_MODE=mock for the deterministic mock |
Planner answers 422 |
send manifest_id and target in the request body |
Scene synthesis answers 503 |
its orchestrator is not configured; starting the service alone is not enough |
A decision on a learner contribution answers 503 ("decisions are disabled") |
set the same STUDIUM_REVIEW_TOKEN, at least 32 characters, on scene-synth and on the teacher dashboard's server; see learner contributions |
| A "live" run returns mock output | check the mode, URL, model aliases and fallback flags: an HTTP 200 does not prove that a model answered |
Checks that do not need a chat
From the repository root:
node apps/lesson-mcp/scripts/headless_smoke.mjs # MCP server, in memory, no client needed
node apps/lesson-mcp/scripts/http-smoke.mjs new-api-audit # HTTP API and report export; needs .venv
The first prints all 19 assertions passed. The second starts a temporary API server, drives it from
several client processes with synthetic answers, exports and verifies a report, then stops; its output
folder must not exist yet. Neither checks your assistant's sign-in, the VS Code pane, or whether a course
teaches well. The full test suites are described in Testing.
If the problem persists, report it: the step, the expected result, the reduced error, the revision, your platform and a minimal reproduction. Do not publish a whole data folder, and do not bypass a check or a protection to get a green light.