Seongwoo Choi / Journal

vLLM out of memory: find the cause in six checks

At a glancevLLM runs out of memory in three different ways: at startup, under load, and in system RAM. Six checks that tell them apart, with the fix for each.

Not testedWritten from the vLLM and Qwen documentation. None of the failures was reproduced: there was no GPU.

In this article 8 sections
  1. 1. Three kinds of "out of memory"
  2. 2. Check one: is something else on the card?
  3. 3. Check two: do the weights fit at all?
  4. 4. Check three: does one full request fit?
  5. 5. Check four: does it start fine and struggle later?
  6. 6. Check five: did the process just disappear?
  7. 7. Check six: the last few hundred megabytes
  8. 8. The short version

"Out of memory" from vLLM is three different problems with one name. The model may not fit when it loads. It may fit and then run short when many requests arrive. Or the machine's ordinary RAM, not the GPU, may be what ran out. Each has a different fix, and the common reflex of lowering one flag at random often makes things worse. These six checks, in order, tell you which problem you have.

1. Three kinds of "out of memory"

At startupThe server never becomes ready. The weights, or one full request, do not fit on the GPU.
Under loadIt starts, then slows or stalls. The cache for requests is full.
In system RAMThe process vanishes with no Python error. The operating system killed it.
Find out which of the three you have before you change anything.

GPU memory in vLLM is split between two things: the model's weights, which are fixed, and the KV cache, which holds the tokens of every request being answered. The cache gets whatever is left after the weights. Nearly every GPU memory problem is one of those two being too big for the card.

2. Check one: is something else on the card?

Before blaming the model, look at the GPU:

nvidia-smi

The table at the bottom lists every process and the memory it holds. A forgotten notebook, a second server or a previous container that did not stop are the usual finds. vLLM reports this case in words. Its source code raises an error of this form:

Free memory on device cuda:0 (X/Y GiB) on startup is less than desired GPU memory utilization (...). Decrease GPU memory utilization or reduce GPU memory used by other processes.

The fix is in the last sentence. Stop the other process, or give this server a different GPU with --gpus device=1 in Docker.

If two servers are meant to share one card, set --gpu-memory-utilization on each, for example 0.5 and 0.5. That is what the flag is for: the documentation describes an explicit value as a hard cap on everything the instance uses.

3. Check two: do the weights fit at all?

Add up the weight files in the model's repository and compare with the card. Divide bytes by 1,073,741,824 to get the GiB that GPU tools report.

ModelWeightsSmallest single card that holds them
Qwen2.5-7B-Instruct14.2 GiB24 GB
Qwen3-8B15.3 GiB24 GB
Qwen2.5-Coder-32B-Instruct61.0 GiB80 GB
Phind-CodeLlama-34B-v262.9 GiB80 GB

If the weights alone are larger than the card, no flag will help. The documentation's options are:

  • Split the model across GPUs with --tensor-parallel-size. This is the standard answer for a model too large for one card.
  • Use a quantized build. Smaller weights at lower precision. Pre-quantized models from the Hub load without extra settings.
  • Choose a smaller model. Often the honest answer for a 24 GB card.
  • Offload part to system memory with --cpu-offload-gb. The reference describes it as a virtual way to enlarge the GPU. Expect it to be much slower; treat it as a way to test, not to serve.

4. Check three: does one full request fit?

This is the most common startup failure, and the least obvious. The weights fit, but the memory left over cannot hold even one request at the model's full context length.

The default context comes from the model's own configuration and is often large. Qwen3-8B defaults to 40,960 tokens, and one request of that length needs about 5.6 GiB of cache. On a 24 GB card that is nearly everything that remains:

Qwen3-8B on 24 GiB, default context of 40,960room for 1 full request

weights 15.3cache 6.3

Same card, --max-model-len 8192room for 5 full requests

weights 15.3cache 6.3

Model weightsKV cacheRuntime reserve, assumed 10%

The memory is identical. Only the size of one request changed, from 5.6 GiB to 1.1 GiB.

The fix is one flag. It is also the first suggestion in the Qwen documentation's own FAQ:

--max-model-len 8192

Pick the largest value your users really need. Then confirm in the startup log, where vLLM prints the real numbers:

GPU KV cache size: 643,232 tokens
Maximum concurrency for 40,960 tokens per request: 15.70x

If the second number is below 1, one full request does not fit. Lower --max-model-len until it is comfortably above the number of requests you expect at once.

5. Check four: does it start fine and struggle later?

When the cache fills up during use, vLLM does not crash. It pauses some requests and recomputes them later, and writes a warning like this one from the documentation:

WARNING ... Sequence group 0 is preempted by PreemptionMode.RECOMPUTE mode because there is not enough KV cache space. This can affect the end-to-end performance. Increase gpu_memory_utilization or tensor_parallel_size to provide more KV cache memory.

Users feel this as answers that stop in the middle and resume. The documentation lists the remedies:

  1. Leave --gpu-memory-utilization unset, or raise it if you lowered it.
  2. Lower --max-num-seqs or --max-num-batched-tokens, so fewer requests run at once and the rest wait their turn.
  3. Add GPUs with --tensor-parallel-size, which leaves more of each card free for the cache.

The second is usually the right first move. A short queue costs users far less than work that is thrown away and redone.

6. Check five: did the process just disappear?

If the container stops with no Python traceback, the GPU is probably innocent. Linux kills a process that uses more system RAM than is available, and it does so without asking. Two commands confirm it:

docker inspect --format '{{.State.OOMKilled}} exit={{.State.ExitCode}}' vllm
sudo dmesg -T | grep -i -E "out of memory|killed process"

true exit=137 from the first, or a "Killed process" line from the second, means system memory ran out. Model weights pass through RAM on their way to the GPU, so a machine with a large GPU and little RAM fails exactly this way. The troubleshooting page also warns that a model too large for RAM makes the system swap, which looks like a hang.

  • Give the machine, or the container, more memory. As a rule of thumb, plan for at least the size of the weight files.
  • Keep the model cache on a local disk, not a network file system.
  • For models that accept images, the documentation notes a processor cache of 4 GiB by default, set by mm_processor_cache_gb, which you can lower.
  • Errors that mention shared memory are a different limit: add --ipc=host to the Docker command.

7. Check six: the last few hundred megabytes

If you are close to fitting, two smaller items remain.

CUDA graphs. vLLM speeds up inference with CUDA graphs, which the documentation says take extra GPU memory. --enforce-eager turns them off. The model runs slower, so use it to confirm a diagnosis or to squeeze onto a small card, not as a default.

An outdated habit. Many older guides tell you to lower --gpu-memory-utilization when you see an out-of-memory error. On current vLLM with NVIDIA GPUs that is usually backwards. The documentation says the server measures free memory after loading and sizes the cache from it, that the setting defaults to 1.0 there, and that anything below 1.0 takes memory away from the cache. Lower it only to leave room for something else on the same card.

8. The short version

What you seeMost likely causeFirst thing to try
"Free memory on device ... is less than desired"Another process holds the GPUnvidia-smi, then stop it
CUDA out of memory while loading weightsThe weights are larger than the cardA quantized or smaller model, or more GPUs
Fails right after loading, or concurrency below 1One full-length request does not fitLower --max-model-len
Preemption warnings, answers that stallThe cache is full under loadLower --max-num-seqs
Container gone, exit code 137System RAM ran outMore RAM; check dmesg
Loading takes forever, disk is busyThe machine is swappingMore RAM, local disk
Fits on some starts and not othersSomething else uses the card at timesGive vLLM its own GPU
Change one thing at a timeEach flag here trades something away: context length, concurrency, speed or precision. Change one, restart, and read the two startup lines again. That way you know what each change bought.

To work out the numbers before you start a server, use the script in GPU sizing for vLLM. To see memory pressure building before users notice, the cache gauge and the preemption counter are on the dashboards in the monitoring guide.

Sources

This article reflects public information available when it was written. Versions, defaults and prices can change; check the linked official documentation.

The causes and fixes come from the vLLM and Qwen documentation as read on November 12, 2026, and one error message is quoted from vLLM's source code on the same day. The memory figures are calculated from published model files. No GPU was available, so none of these failures was reproduced for this article; the Docker and Linux commands are standard ones. Written for this site with AI assistance, from the sources above. For errors or additional information, please request a correction. Editorial policy