Jan Won’t Start? 5 Errors I Fixed on Linux and Mac

Jan looked clean and straightforward when I first installed it—open-source, runs offline, familiar chat interface. Then it wouldn’t start. The app would hang on launch, models would fail to load, the API would silently die. I spent a weekend digging through logs and trying different fixes. Here are the actual problems I hit and what got the thing running.

Jan Process Hangs on Startup with No Error Message

This was the first one. I’d click the app icon, wait 30 seconds, nothing. No crash dialog, no error in logs. The process was running according to ps, but the UI never appeared.

I checked ~/.jan on Linux (or ~/Library/Application Support/Jan on Mac) and found the config was being created. The backend seemed to be starting. I ran the app from terminal to see stdout:

./jan --verbose

Got nothing useful. Then I realized the issue was GPU detection. Jan was trying to initialize CUDA on my GTX 1660, failing silently, and just hanging. The app doesn’t report GPU init failures—it just freezes.

The fix: disable GPU in the settings before first run. Edit ~/Library/Application Support/Jan/settings.json (or ~/.jan/settings.json on Linux) and set:

{
  "gpu": false,
  "gpu_devices": [],
  "cpu_threads": 4
}

Once I did that, Jan opened in about 8 seconds. I could then go into the UI settings and configure GPU properly if I wanted. The real issue is that Jan should fail loudly, not silently timeout. But that’s the way it is.

Model Download Fails Midway with Connection Reset

Next problem: I tried downloading Mistral 7B. Got to maybe 40% of the 4GB download and it just stopped. No retry, no clear error, just a dead connection.

Checked the logs at ~/.jan/logs and saw timeout errors. Jan’s download doesn’t have resume support built in—if the connection drops, you start over. That’s annoying on slower connections or over Tailscale.

I fixed it by downloading the model manually from Hugging Face and placing it in the right directory. Found where Jan stores models:

# Linux/Mac
~/.jan/models/llm/

Downloaded the GGUF file directly (about 5 minutes on my connection), dropped it in that folder, and Jan picked it up immediately. The app scanned the directory on next startup and added it to the available models list. That’s actually faster than using the built-in downloader.

API Server Starts but Localhost:1337 Refuses Connections

I wanted to test Jan’s local API with another client. The app said it was running, but curl http://localhost:1337/health timed out. Port was open according to netstat -tuln, but nothing was listening on it.

Turns out Jan had the API server configured but not enabled by default. Check your settings.json again:

{
  "api": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 1337,
    "openai_compatibility": true
  }
}

The enabled flag was missing. Once I added it and restarted the app, the API responded:

curl http://localhost:1337/health
{"status": "ok"}

This matters if you’re planning to use Jan as a backend for other tools. The UI works fine without it, but if you want to integrate it with something like Continue or Open WebUI, you need this running and confirmed.

Memory Exhaustion When Running Larger Models

I loaded a 13B model and tried a long conversation. After about 20 exchanges, the system started swapping hard and Jan became unusable. Wasn’t a crash, just extreme slowdown.

Jan doesn’t have good built-in memory management or context pruning. It’ll load the entire model and keep growing the context window until your system hits swap. On a machine with 16GB RAM, a 13B model at full precision can use 26GB including overhead.

Two actual fixes here. First, use quantized models. Jan supports GGUF format, which includes 4-bit and 8-bit quantized versions. A 13B model at Q4 takes about 7GB instead of 26GB, with minimal quality loss. Downloaded the quantized version from Hugging Face instead of the full-precision one.

Second, configure a context limit in the model settings. In Jan’s chat interface, before starting a conversation, set max context tokens to something your hardware can handle—2048 or 4096 instead of the default 8192:

Model Settings → Advanced → Context Length: 2048

After that, the 13B model ran smoothly on my machine. Still used swap occasionally, but nothing catastrophic.

Jan Extension Won’t Load or Causes Crashes

Jan supports extensions. I tried installing one (think it was for better web search), and it either wouldn’t load or Jan would crash on startup the moment the extension initialized.

No clear error for either case. Extensions in Jan are somewhat experimental—they’re just JavaScript that the app loads at runtime, and debugging is hard.

Solution: disable extensions. Check your settings.json:

{
  "extensions": [],
  "disabled_extensions": ["search", "whatever-broke"]
}

Or just move the extension folder out of ~/.jan/extensions and restart the app. Once it’s stable again, you can debug the specific extension or update it.

If you’re planning to use Jan for production-like stuff, I’d avoid extensions for now. The core chat and API work solid. The extension ecosystem is still rough.

Jan Forgets Settings After Restart

Less critical but annoying: I’d configure a model to use 4 CPU threads, set the API to enabled, adjust the theme. Close the app. Restart it. Some settings stuck, others reverted to defaults.

This usually happens if the settings file is corrupted or Jan crashes while writing to it. I fixed it by backing up settings.json, deleting it, and letting Jan create a fresh one on the next start. Then I reconfigured from scratch.

cd ~/.jan
cp settings.json settings.json.backup
rm settings.json
# Restart Jan

It’s not elegant, but it works. If you’re tweaking settings a lot, export them periodically—Jan doesn’t have a built-in backup or versioning system. The config is just JSON, so you can version control it yourself if you want to be serious about it.

What Actually Helped

The biggest lesson: Jan’s error reporting is weak. Silent failures, timeouts that look like hangs, vague API errors. You’ll spend more time debugging Jan than using it, at least initially. Reading the logs directory is mandatory. So is running the app from terminal occasionally to catch stdout.

The app itself is solid once it’s configured. The chat is fast, model switching is seamless, the offline aspect actually works—no API calls home, no sneaky telemetry that I can find. But the setup and troubleshooting will test your patience. If you’re comfortable editing JSON and reading logs, you’ll be fine. If you expect a frictionless GUI experience, go with something that costs money.

FAQ

Can Jan run without a GPU?

Yes. Jan defaults to CPU mode if GPU detection fails or if you disable it in settings. A decent CPU (6+ cores) will run small models like Mistral 7B adequately, though inference will be slower than GPU acceleration. Quantized 4-bit models help significantly on CPU.

How much RAM does Jan need?

Minimum 8GB, realistically 16GB if you want to run 13B models without constant swap. A 7B quantized model needs about 8GB including overhead. Larger models scale roughly with their parameter count—a 70B model in 4-bit quantization still needs 35-40GB.

Is Jan faster than Ollama?

Jan and Ollama are different tools. Ollama is a backend server; Jan is a desktop app with a built-in server. Jan’s inference speed depends on your hardware, same as Ollama. Jan’s UI is smoother if you just want to chat. If you want maximum flexibility and integration with other tools, Ollama + a separate UI is often better.

Does Jan work on Windows?

Yes, Jan runs on Windows, Mac, and Linux. Windows support is solid, though some users report GPU detection is trickier there—you may need to manually configure NVIDIA or AMD drivers. The basic CPU experience works fine.

Can I run multiple models at once in Jan?

No. Jan runs one model at a time. You can switch between them instantly (they stay loaded in memory), but you can’t parallel-load two different models. If you need that, you’d need multiple Jan instances or a tool like Ollama with a load balancer.

Explore Jan in our AI Homelab Toolkit.