CPU & Memory Hot-Plug
Scale your virtual machine's CPU and memory without rebooting. Add vCPUs or increase RAM while the guest is running.
How It Works
When you create a VM through the Vapor wizard, it automatically pre-configures the VM for CPU hot-plug. Memory hot-plug requires you to enable it explicitly during creation.
| Setting | Default Behavior | Hot-Plug Ready? |
|---|---|---|
| Max vCPUs | Auto-calculated as min(max(vcpus × 2, 8), host cores) | Always |
| Max Memory | Same as Memory | Only if Max Memory > Memory |
CPU Headroom (Automatic)
When you leave Max vCPUs empty in the wizard, Vapor calculates a reasonable upper limit. For example, creating a 2-vCPU VM on a 16-core host gives you max_vcpus = 8 — instant headroom for hot-plug.
- Formula:
max_vcpus = min(max(vcpus × 2, 8), host_cores) - The VM's CPU topology (sockets, dies, cores, threads) is automatically adjusted to match.
- Your VM can immediately accept live vCPU additions up to the
max_vcpuslimit.
Memory Headroom (Must Be Enabled)
To grow memory beyond the initial allocation while the VM is running, set Max Memory higher than Memory when creating the VM. You'll find this in the Compute Options panel (click More Options in the creation wizard).
| Max Memory Setting | Live Behavior |
|---|---|
| Same as Memory (default) | Memory can only shrink/inflate within the current allocation via the balloon driver |
| Higher than Memory | Balloon + DIMM hot-add — you can grow memory up to the Max Memory limit without restarting |
How to Hot-Plug (Edit Wizard)
- Open the VM detail drawer by clicking the VM name in the list.
- Click the Edit button at the top.
- The edit wizard opens. Adjust the values:
- vCPUs — increase as needed, up to the Max vCPUs ceiling.
- Memory — increase or decrease as needed.
- Click Save. Changes apply immediately if the VM supports live hot-plug.
If you adjust values that require a restart (such as changing the vCPU ceiling or memory ceiling), the changes are saved to the persistent configuration and take effect on the next VM boot.
What You Can Change on a Running VM
| Change | Effect |
|---|---|
| Increase vCPUs (within Max vCPUs) | Live — applies immediately |
| Increase memory (within Max Memory) | Live — balloon or DIMM hot-add |
| Decrease memory | Live — balloon driver |
| Raise Max vCPUs or Max Memory | Saved to config, applies after restart |
| Change firmware (UEFI, Secure Boot, TPM) | Disabled — VM must be stopped first |
| Change CPU topology (sockets, cores) | Config-only — applies after restart |
Common Error Messages
These messages appear as toast alerts in the top-right corner of the UI, or as inline warnings in the form.
| Message | Cause & Solution |
|---|---|
| This operation requires the VM to be stopped. | You tried to change firmware, machine type, or PCI passthrough on a running VM. Stop the VM first. |
| Failed to add CPU. | vCPU hot-plug failed. The VM may not have headroom — when editing, make sure Max vCPUs is larger than vCPUs. Also check the guest supports CPU hot-plug. |
| Failed to add memory. | Memory hot-plug failed. The balloon driver may be missing in the guest, or DIMM hot-add slots are exhausted. |
| Hotplug operation failed. | A general hot-plug error. Check the server logs for details. |
| Hotplug is not supported for this resource. | The VM configuration doesn't support the requested hot-plug operation. |
Inline Warnings (Wizard Form)
| Message | Where It Appears | Meaning |
|---|---|---|
| ⚠ Mismatch with max_vcpus (X). max_vcpus will be updated to Y. | Compute Options modal | The topology product (sockets × dies × cores × threads) doesn't match Max vCPUs. The value auto-corrects when you save. |
| Firmware, machine type, and PCI passthrough edits are disabled until the VM is stopped. | Edit wizard header | You opened the edit wizard on a running VM. Fields that require a stop are locked. |
Troubleshooting
"DIMM hot-add unavailable" in server logs
Cause: VM was created without Max Memory > Memory. Fix: Stop the VM, open the Edit wizard, set Max Memory higher than Memory, start the VM.
Guest doesn't see new CPUs after hot-plug
echo 1 | tee /sys/devices/system/cpu/cpu*/onlineGuest doesn't see new memory after hot-plug
grep -l offline /sys/devices/system/memory/memory*/state | while read f; do echo online > "$f"; done