Troubleshooting

Use this page when Jarvis does not start, the UI cannot connect, or a runtime session does not appear in the workspace.

Goal

Move from a vague failure to the first concrete failing layer: Node, Python, port binding, database path, API key, provider credentials, or runtime CLI setup.

Fast checks

Symptom	First check	What it tells you
Frontend build fails with `crypto.hash is not a function`	`node -v`	Node is below the required version. Use Node 20.19 or newer.
Browser cannot open local Jarvis	`lsof -i :8888`	Another process may own the default port.
UI asks for auth repeatedly	Regenerate an API key and paste the new value	The browser may have an expired or wrong key.
Runtime does not launch	Run the runtime CLI directly	Jarvis uses the user’s local Claude Code, Codex, or OpenCode configuration.
Chat history looks empty	Check `JARVIS_DATABASE_PATH`	The process may be using a different SQLite database.

Verify the backend

Start Jarvis from the repository root:

./restart.sh

Then check health:

curl -s http://127.0.0.1:8888/api/v1/health

Expected result:

a JSON response
status is healthy or OK
the version matches the build you intended to run

Check logs

Jarvis writes local logs under data/logs/ in the repository checkout:

tail -f data/logs/jarvis.stdout.log
tail -f data/logs/jarvis.stderr.log

Before posting logs publicly, remove API keys, provider base URLs, private prompts, transcript content, and local filesystem paths that identify a user or machine.

Runtime troubleshooting

Jarvis does not replace runtime CLI authentication. If a runtime fails:

Run the runtime CLI outside Jarvis.
Confirm the CLI can start in the target workspace.
Confirm the Jarvis UI points to the workspace you expect.
Inspect the coding session panel for blocked, unavailable, or exited state.