Debugging

Most user-reported bugs land in one of three places: the daemon, a runner subprocess, or a launch integration. Each has its own debug knob.

Logs

The daemon and the runner subprocess log through slog to stderr. Verbosity is controlled by OLLAMA_DEBUG:

• OLLAMA_DEBUG=0 — default; warnings and errors only.
• OLLAMA_DEBUG=1 — info-level (model loads, request lifecycle).
• OLLAMA_DEBUG=2 — debug-level (token streams, scheduler decisions, runner stdout).

The daemon configures the logger in logutil/ and applies the level from envconfig.Debug() in envconfig/config.go.

When a runner subprocess crashes, the daemon captures its tail stderr in llmServer.status (llm/server.go, see StatusWriter in llm/status.go) and surfaces it as the request error.

Useful environment variables

The full list is in envconfig/config.go. The most common debug knobs:

Variable	Effect
OLLAMA_DEBUG	Log level.
OLLAMA_HOST	Where the daemon listens / where the CLI connects.
OLLAMA_MODELS	Override the local model store directory.
OLLAMA_KEEP_ALIVE	How long the scheduler keeps a runner loaded. Try 0 to verify reload behavior.
OLLAMA_MAX_QUEUE	Pending request queue depth before the scheduler returns 503.
OLLAMA_NUM_PARALLEL	Concurrent requests per loaded runner.
OLLAMA_LLM_LIBRARY	Force a specific GPU library (cuda_v12, rocm, cpu).
OLLAMA_GPU_OVERHEAD	Reserve VRAM headroom (handy on cards with display drivers eating memory).
OLLAMA_NOPRUNE	Skip the orphan-blob garbage collector on startup.
OLLAMA_FLASH_ATTENTION, OLLAMA_KV_CACHE_TYPE	Tweak inference behavior.
OLLAMA_EXPERIMENT	Comma-separated experiments (e.g., client2).

Common failure modes

"model not found"

The pull from the registry didn't complete or the manifest is missing. Check ~/.ollama/models/manifests/registry.ollama.ai/library/<name>/ and re-run ollama pull <name>. The server-side handler is ShowHandler in server/routes.go.

"remote model is unavailable" / cloud errors

These come from server/cloud_proxy.go. The local daemon couldn't talk to ollama.com — typical causes are OLLAMA_HOST pointing at a remote daemon that lacks credentials, or a missing key (auth.GetPublicKey()). Re-sign in with ollama signin.

Runner crashes immediately on load

Look at the daemon's stderr. The first non-error line is usually the runner's own startup log; llm/server.go will surface the runner's last status string. Common causes:

• VRAM exhaustion (try OLLAMA_GPU_OVERHEAD=1073741824 to reserve 1 GiB).
• A model architecture not supported by the chosen runner. Use --ollama-engine or --mlx-engine to switch backends.
• A CGO mismatch after a llama.cpp sync — go clean -cache then rebuild.

/api/chat hangs at the first token

The runner started but is recompiling kernels (CUDA / ROCm) or the GPU is being throttled. Watch with nvidia-smi / rocm-smi.

ollama launch <integration> writes the wrong config

Each integration's tests in cmd/launch/<name>_test.go cover the config-rewriting behavior. Reproduce in a unit test before changing the integration; the maintainers will ask for one in review anyway.

Tracing a request

1. OLLAMA_DEBUG=2 ollama serve shows the request landing on the gin router.
2. The same log prints the scheduler's loadFn decision (load, reuse, or evict).
3. The runner subprocess logs its /completion stream tokens.
4. Native compat endpoints add a translation step — see middleware logs from middleware/.

When the desktop app misbehaves

The macOS / Windows app under app/ launches the same ollama binary with serve. If the tray reports failures, kill the tray, run ollama serve from a terminal with OLLAMA_DEBUG=2, and reproduce.