Dennis HilkLinux Fix LabDE

Performance & Virtualization

CPU placement and memory policy do not align

A NUMA workload runs far from its memory or fails policy setup. Inspect topology, allowed nodes and process page placement before adding hard bindings.

Editorial source review: Start with the evidenceShare this guide
On this page
  1. Symptoms & scope
  2. Possible causes
  3. Diagnose safely
  4. Evidence-guided next steps
  5. References & review
  6. Related problems

Symptoms & scope

  • A memory-intensive workload has variable throughput after CPU pinning.
  • A systemd unit with NUMAPolicy exits with NUMA_POLICY.

Relevant environment

Linux multi-node NUMA hosts or guests; a single-node system does not gain remote-memory locality tuning.

Recognizable messages (synthetic examples)
systemd[1]: example.service: Main process exited, code=exited, status=242/NUMA_POLICY

This is a startup policy failure, not proof that remote-memory traffic caused a running workload's slowdown.

Possible causes

These are possible explanations, not a confirmed diagnosis. Several independent faults can coexist.

  • CPU affinity and memory placement may refer to different nodes after migration or first-touch allocation.
  • A policy mask may name unavailable nodes or conflict with the task's allowed cpuset memory nodes.

Diagnose safely

Run one command at a time in the relevant session. Read the explanation first. Uppercase placeholders need your own values; tools and privileges vary by distribution. These commands are displayed here and never executed by the website.

Check 1

Read-only NUMA topology from the installed numactl tool.

numactl --hardware

Interpret the result: Compare node CPU sets, available memory and distance matrix. One node means this remote-locality hypothesis is inapplicable.

Check 2

Replace 1234 with the workload PID; proc access may require its owner or an authorized administrator.

cat /proc/1234/numa_maps

Interpret the result: N0/N1 counts show where mapped pages currently reside; policy labels show requested behavior. Shared mappings and migration mean one snapshot is not a latency measurement.

Check 3

Replace the affected unit; reads configured policy without changing affinity.

systemctl show example.service -p NUMAPolicy -p NUMAMask -p CPUAffinity -p AllowedMemoryNodes

Interpret the result: Compare the memory mask with actual available and allowed nodes. CPUAffinity alone does not make already allocated memory local.

Evidence-guided next steps

Align placement with measured locality

If topology and page placement support a locality problem, trial CPU and memory placement together using a supported launch-time policy. Reinitialize or restart the workload in a controlled window so first-touch placement follows the intended node.

Precautions: Hard binding can fail allocations while other nodes have free memory. Changing CPU affinity does not automatically migrate every existing page.

Recovery / rollback: Restore original launch policy and affinity and restart the workload with its previous placement.

Did this solution help you?

Share this solution#

Correct an invalid or overly strict node mask

If policy setup fails because the mask is invalid or excluded by the cpuset, select valid allowed nodes or return to the documented default/preferred policy. Use interleave only for a workload whose measured bandwidth benefits justify it.

Precautions: Policy names have different allocation fallback behavior. Check the installed systemd and kernel support before keeping a policy.

Recovery / rollback: Restore the recorded NUMAPolicy, NUMAMask and cpuset settings and recheck topology plus application startup.

Did this solution help you?

Share this solution#

References & review

This guide was prepared from primary project or distribution sources and reviewed on the date shown. This is an editorial source check, not evidence that a fix was reproduced on your hardware. Diagnostic log examples are synthetic fixtures. Version-dependent details must be checked against your installed release.