Skip to content
Français
Account: not signed in, sync available My learning
Select theme
Français
Lire en français

Ollama: troubleshooting and configuration

16 min read
Improve this page

Logo Ollama

Ollama is simple, but four traps come back again and again: the server does not respond, a model saturates memory, an environment variable is ignored, or port 11434 is exposed without you wanting it. This lesson first gives a quick diagnosis table, then the detail of each case and the useful configuration on Linux with the systemd service: model location, variables, load limits, the num_ctx context. The facts come from the official Ollama documentation (FAQ, Linux and troubleshooting guides), reviewed on 15 October 2026. The command outputs were captured on 11 November 2026 on Ollama 0.40.16, installed with the official script on a Debian 13 virtual machine (systemd 257), processor only.

What you will learn

  • Make a quick diagnosis from the symptom
  • Find where Ollama stores its models and read its logs
  • Set environment variables with systemctl edit rather than export
  • Check whether the model runs on the GPU or the CPU with ollama ps
  • Understand the num_ctx context and its memory cost
  • Secure access to port 11434

Prerequisites

Ollama must already be installed, as in Ollama: installation and first steps. The configuration commands assume Linux with the systemd service created by the official installation script; the specifics of macOS and Windows are flagged where they differ.

What is the quick diagnosis for Ollama?

This table starts from the symptom you see and points to the most likely cause, the command that confirms it and the fix. Read it from left to right and go to the matching detailed section only if the row is not enough.

SymptomLikely causeCheckFix
could not connect to ollamaService stoppedsystemctl status ollamasudo systemctl start ollama
address already in use when running ollama serveThe systemd service already holds port 11434sudo ss -ltnp (look for 11434)Do not run ollama serve by hand, configure the service
An export variable has no effectThe service does not read your shellsystemctl show ollama -p Environmentsudo systemctl edit ollama.service then restart
model '<name>' not found (SDK, API) or Error: pull model manifest: ... (ollama run)Model missing from local storage; ollama run tries to download it firstollama listollama pull <model>
Very slow answersModel on CPU or overflowing the GPUPROCESSOR column of ollama psSmaller model, reduced context
Memory saturated with a small modelReserved context too largeCONTEXT column of ollama psReduce num_ctx
The start of the conversation is forgottenContext exceededollama psIncrease num_ctx if memory allows

What to do when Ollama answers "could not connect to ollama"?

This error means the ollama command finds no server listening on 127.0.0.1:11434. On Linux with the official installation script, this server is a systemd service named ollama:

Terminal window
sudo systemctl status ollama
sudo systemctl start ollama

The status command must show active (running). If the service crashes at startup, read its logs with journalctl -u ollama --no-pager --follow --pager-end, the command given by the official documentation. On macOS, check that the Ollama icon is in the menu bar; on Windows, in the notification area, and relaunch the application otherwise.

One possible cause when you configure things by hand: an ollama serve started in a terminal while the service is already running. The two fight over port 11434, and the second one fails with an address-already-in-use error:

Error: listen tcp 127.0.0.1:11434: bind: address already in use

Check who holds it with sudo ss -ltnp, which lists the listening TCP ports (-l listening, -t TCP, -n port numbers, -p processes). The sudo is what makes the process appear: without it, the column stays empty. An ollama line on port 11434 proves the service already holds it, so let it manage the server alone:

LISTEN 0 4096 127.0.0.1:11434 0.0.0.0:* users:(("ollama",pid=2459,fd=3))

What to do when Ollama answers "model not found"?

This message means the requested model is not in Ollama's local storage, and it takes two forms depending on the tool. With the Python SDK or the API, a missing model gives model 'inconnu:1b' not found (status code: 404). With ollama run, Ollama 0.40.16 first tries to download the model: without access to registry.ollama.ai, the error shown is then Error: pull model manifest: ..., not model not found.

In both cases, list what is installed, then download the missing model:

Terminal window
ollama list
ollama pull llama3.2:3b

Check the exact name with its tag: llama3.2 and llama3.2:3b do not necessarily designate the same file. The output of ollama list must show the model with its size before you rerun your command.

How do you know whether Ollama uses the GPU?

The ollama ps command lists the models loaded in memory, and its PROCESSOR column says where they run: on the GPU (the graphics card) or on the CPU (the processor). According to the official documentation, 100% GPU means a model fully loaded on the GPU, 100% CPU fully in system memory, and a value such as 48%/52% CPU/GPU a model split between the two.

Terminal window
ollama run llama3.2:3b "Test"
ollama ps

On Ollama 0.40.16, on a machine with no GPU, the output looks like this:

NAME ID SIZE PROCESSOR CONTEXT RUNNER UNTIL
llama3.2:3b a80c4f17acd5 2.6 GB 100% CPU 4096 llamacpp 4 minutes from now

The llama3.2:3b model takes up 2.6 GB in memory for a 2.0 GB file, because the 4096-token context is reserved on top of the weights. The UNTIL column tells when the model will be unloaded: it comes from OLLAMA_KEEP_ALIVE, presented further down.

First send a request to load the model, then read ollama ps: it is the reliable check, nvidia-smi being only a complement for an NVIDIA card. A model split between CPU and GPU is much slower than a model entirely on the GPU: pick a smaller model, or reduce the context (explained further down).

If the GPU is never used, enable OLLAMA_DEBUG=1 in the service override (the method is detailed further down, in the section on systemd variables). The documentation states that this mode adds information during GPU detection. After a restart of the service, sudo journalctl -u ollama --no-pager then contains level=DEBUG lines, absent in normal mode.

What to do when the model runs out of memory or answers too slowly?

A model too big for your machine overflows memory and slows everything down. First switch to a smaller model, for example llama3.2:3b instead of a 7-billion-parameter model such as mistral; the lesson Ollama: choosing your model in 2026 tells which model for which amount of VRAM (the graphics card's memory). Then watch memory with free -h or htop on Linux, or the Task Manager on Windows.

The first request after a launch is longer, because the model has to be loaded into memory. It then stays there for the duration of OLLAMA_KEEP_ALIVE, 5 minutes by default: after that delay with no request, it is unloaded and the next request pays the loading cost again.

What to do when the answers are inconsistent?

A model that answers off-topic or loops may lack precision in the question or drag along a history that is too long. Rephrase with more context, try another model (each has its strengths), or start again from an empty conversation with /bye then a new ollama run session. If the problem only appears at the end of a conversation, suspect the context, covered further down.

Where does Ollama store its models?

The folder depends on how Ollama runs. On Linux with the systemd service of the official installation script, the documentation gives /usr/share/ollama/.ollama/models: the service runs under the ollama system user, whose home directory is /usr/share/ollama. On macOS and Windows, models are in .ollama/models, in the user's home directory.

An ollama serve started by hand under your account uses ~/.ollama/models. It therefore does not see the service's models: a second server started under an ordinary account shows an empty ollama list. This is one possible cause of model not found after a change of launch mode.

To move the storage to a bigger disk, set the OLLAMA_MODELS variable (method in the next section). The service runs under the ollama user: the new folder must therefore belong to it, with read and write access. Otherwise, the service fails in a loop with Error: mkdir /srv/ollama: permission denied: ensure path elements are traversable, and systemctl status ollama shows activating (auto-restart).

To move models that are already downloaded, stop the service, copy the original folder, give the copy to ollama and check the result before restarting:

Terminal window
sudo systemctl stop ollama
sudo mkdir -p /srv/ollama
sudo cp -a /usr/share/ollama/.ollama/models /srv/ollama/models
sudo chown -R ollama:ollama /srv/ollama
ls -ld /srv/ollama /srv/ollama/models

Both lines of ls -ld must show ollama ollama as owner and group. Then set OLLAMA_MODELS as described below: the restart that follows relaunches the stopped service.

How do you set an environment variable with systemd?

A variable exported in your shell (export OLLAMA_MODELS=...) reaches only the processes started from that shell. The systemd service, started by the system, never sees it, and running ollama serve by hand to apply it conflicts with the service on port 11434. The official documentation prescribes the service method: open an override file with systemctl edit, declare each variable under [Service] with Environment=, then restart the service.

Terminal window
sudo systemctl edit ollama.service

systemctl edit opens the editor of your choice (SYSTEMD_EDITOR or EDITOR variable) and refuses to run outside an interactive terminal. In the editor that opens, add for example:

[Service]
Environment="OLLAMA_MODELS=/srv/ollama/models"
Environment="OLLAMA_KEEP_ALIVE=10m"

Save, then restart the service and read back its environment:

Terminal window
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama -p Environment

systemctl edit saves the file under /etc/systemd/system/ollama.service.d/override.conf and already reloads the configuration: the daemon-reload is harmless, but only the restart makes the server read the variables. The last command must show your two variables after the service's PATH:

Environment=PATH=/usr/local/bin:/usr/bin:/bin:/usr/games OLLAMA_MODELS=/srv/ollama/models OLLAMA_KEEP_ALIVE=10m

After a restart and a request, the UNTIL column of ollama ps then shows 9 minutes from now instead of 4 minutes from now, proof that OLLAMA_KEEP_ALIVE=10m is read. On macOS and Windows, variables are set differently (launchctl setenv on macOS, user environment variables on Windows): follow Ollama's official FAQ for those platforms.

Which variables tune memory and load?

Four variables, documented in the official FAQ, tune resource usage. They are set as above, with Environment= in the service override.

VariableEffectDefault value (FAQ)
OLLAMA_MAX_LOADED_MODELSMaximum number of models loaded at the same time3 times the number of GPUs, or 3 for CPU inference
OLLAMA_NUM_PARALLELRequests processed in parallel per model1
OLLAMA_KEEP_ALIVEHow long a model stays in memory after its last request5 minutes
OLLAMA_MAX_QUEUERequests queued before rejection512

To reduce memory, OLLAMA_NUM_PARALLEL and OLLAMA_MAX_LOADED_MODELS are the levers: the FAQ states that the memory required grows with the product of parallelism and context size. OLLAMA_KEEP_ALIVE frees memory sooner when you lower it. By contrast, OLLAMA_MAX_QUEUE does not limit memory: it only bounds the number of waiting requests, beyond which Ollama rejects new ones. Use it to protect a shared service from an endless queue, not to save RAM.

Why does a small model saturate memory? The context trap

The context is the window of tokens (the pieces of words) that the model sees at the same time. It is reserved in memory at load time, on top of the weights: a model of a few gigabytes on disk can therefore take up much more in memory if the context is large. The CONTEXT column of ollama ps shows the allocated value. When this context pushes usage past the VRAM, part of the model moves to the processor: the PROCESSOR column then shows a CPU/GPU split, and answers slow down.

The default value depends on the version and on the available VRAM. The official documentation on context length gives tiers: 4k tokens under 24 GiB of VRAM, 32k between 24 and 48 GiB, 256k from 48 GiB. The FAQ still cites a default window of 4,096 tokens. The two pages do not agree: read the actual value on your machine with ollama ps rather than relying on a figure. On the test machine, with no GPU, the CONTEXT column showed 4096.

To set the context, the FAQ offers the OLLAMA_CONTEXT_LENGTH variable, the /set parameter num_ctx 8192 command in an ollama run session, or the num_ctx option of the API; in a Modelfile, PARAMETER num_ctx 8192. With OLLAMA_CONTEXT_LENGTH=8192 in the service override, ollama ps returned 8192 in the CONTEXT column and a size of 3.1 GB instead of 2.6 GB for llama3.2:3b: on this model, going from 4096 to 8192 tokens cost 0.5 GB of memory.

How do you expose Ollama safely?

By default, Ollama listens on 127.0.0.1:11434, so only from your machine. The OLLAMA_HOST variable changes the listening address; set it in the service override, like the others:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

After a restart, sudo ss -ltnp shows listening on all interfaces instead of 127.0.0.1: the local address becomes *:11434.

Key takeaways

  • A stopped service, a missing model or a conflict on port 11434 block Ollama: check systemctl status ollama, ollama list and sudo ss -ltnp.
  • On Linux, variables are set with sudo systemctl edit ollama.service then a restart, never with export followed by ollama serve.
  • The service's models live in /usr/share/ollama/.ollama/models, not in ~/.ollama/models.
  • ollama ps answers two questions: GPU or CPU (PROCESSOR column) and the size of the reserved context (CONTEXT column).
  • OLLAMA_NUM_PARALLEL, OLLAMA_MAX_LOADED_MODELS and OLLAMA_KEEP_ALIVE tune memory; OLLAMA_MAX_QUEUE only bounds the waiting queue.
  • The context is reserved in memory on top of the weights: reduce num_ctx if a small model saturates memory, increase it if the start of the conversation is forgotten.
  • Ollama has no documented authentication: never expose port 11434 on the Internet.

Knowledge check

Check that you have the essentials of this lesson. The questions cover only what was just explained here.

Knowledge check

Check what you have learned with this interactive quiz

6 questions
6 min
70% to pass

How it works

  • The timer starts when you click Start
  • Multiple choice, true/false and short answer questions
  • You can move between questions
  • Detailed results are shown at the end

Starts the quiz and the timer