# Host swap exists but the container cannot use it: checking limits

Diagnose host swap exists but the container cannot use it: checking limits. Evidence to collect, a worked operational example and recovery checks.

Author: Retrivium team
Updated: 2026-11-01
Canonical URL: https://retrivium.ai/journal/container-swap-limit-mismatch/
Language: en

Host swap does not imply that a container is allowed to use it. Inspect runtime memory settings and the effective cgroup memory.swap.max value. Swap handles system memory pages; it does not become extra VRAM or replace model-specific offload.

## Compare two different views

Record host swap capacity and consumption, then separately inspect the container's memory.current, memory.swap.current, memory.max and memory.swap.max. Confirm that the system uses cgroup v2, since file names and semantics depend on the hierarchy version. A command inside the container may expose host characteristics without describing the workload's actual permission to consume them. A single free output therefore cannot establish available swap for this process. Inspect ancestor cgroup boundaries as well.


[Official reference 1](https://docs.kernel.org/admin-guide/cgroup-v2.html).

## Read Docker options literally

Docker documents a relationship between memory and memory-swap: with a memory limit set, memory-swap describes the combined RAM and swap allowance. Zero, an omitted option and a special negative value should not be treated as interchangeable without consulting the runtime documentation. In cgroup v2, memory.swap.max separately bounds swap use. Compare these layers through effective files after startup rather than relying on a similarly named control in a cloud interface.


[Official reference 2](https://docs.docker.com/engine/containers/resource_constraints/).

## Work through a bounded example

In an illustrative launch, memory is 4 GiB and memory-swap is also 4 GiB. That combination does not grant an additional swap allowance. Changing the latter to 6 GiB establishes a different combined boundary, provided the host has swap and the runtime supports it. These values explain option semantics; they are not advice to move a model's working set into swap. Actual latency depends on page access patterns and the surrounding system.

| Incident field | What it establishes |
| --- | --- |
| Host swap | The resource exists on the node |
| Runtime settings | The requested launch policy |
| memory.swap.max | The effective cgroup boundary |
| memory.swap.current | Actual consumption at observation time |

## Choose pressure behavior deliberately

First assess the normal RAM working set and acceptable delays. Swap may absorb certain bursts, but does not guarantee sustained progress under a permanent shortage. Memory pressure and reclaim can impair response time before OOM occurs. Agree the allowance on a shared node, where consumption competes with other processes. Changing global swap policy for a single symptom requires understanding the wider system effect.

## Verify recreation and latency

After updating declared configuration, recreate a test container and reread its effective boundaries. Repeat the same inputs while recording memory pressure, swap usage, duration and OOM events. Success means useful application behavior rather than merely nonzero swap consumption. Preserve runtime and kernel versions alongside ancestor limits. If the GPU still reports device-memory exhaustion, return to VRAM and model configuration: system swap does not correct that separate error. Keeping both diagnoses distinct prevents a host-memory change from being mistaken for additional accelerator capacity.

Keep swap measurements with their scope. Node activity may grow because of another workload, so timing alone cannot establish swap use by the container being investigated.

Related operational reading: [memory optimized hosting](/journal/memory-optimized-hosting/); [ram vs vram](/journal/ram-vs-vram/).