Images, ISOs and templates

What to do when an image or ISO does not reach a node, a server cannot be made from an image, a container image fails, or a Windows template build stops.

Most image problems show on the Images or ISOs tab (the per-node state of each item), on the node's page under Images and ISOs on this node, and in the build log of the create or reinstall that failed. Start there; the node's own message is in the failed task (System › Tasks). For logs on the node, see Logs.

An image or ISO does not reach a node#

The row says "Failed on node1: …" with one of these reasons. The node tries again after 5 minutes, 30 minutes, then daily; Download again on the node's page tries at once.

Reason What to do
Not enough free space on the node (5% of its volume is kept free) Free space on the node's default storage, or disable images you do not sell. Check with df -h on the node.
The download does not match its checksum The publisher put out a new build behind a "latest" link. Give the image a Checksum source (the publisher's SHA256SUMS or CHECKSUM file) instead of a fixed checksum, or press Refresh checksum now if it has one. See Checksums.
The download is not a usable qcow2 image The link is not a qcow2 cloud image, has a backing file, or is a compressed raw image (.raw.xz is refused). Use the publisher's qcow2 file.
The download is not an ISO image The link gives an HTML page or another file. Open it with curl -I from the node and check the final address.
The ISO is larger than 16 GiB Library ISOs are limited to 16 GiB.
The link could not be downloaded The node cannot reach the address: check DNS and outbound HTTPS from the node, or whether the publisher moved the file.
Needs agent 0.36.0 or later on this node The image is compressed (.xz, .gz, .bz2, .zst) and the node's agent cannot unpack it. Update the agent; the download starts at once.

To test a link from the node itself:

curl -fsSIL https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2
df -h /var/lib/vmstack

Nothing downloads at all: check Download images and ISOs to nodes ahead of time under System › Settings, that the node is online, and that the panel's queue workers run (the downloads are queued jobs on the nodes queue).

"Image checksum cannot be refreshed" (an alert after 3 failed reads): the checksum source cannot be read. The Images page shows why. The source must be a public https:// address, not the panel's own, and must list the image's exact file name.

A server cannot be made from an image#

Message Cause and fix
A plan is shown as "Not available for this image" The plan is smaller than the image's minimum disk or memory. Lower the minimum or use a larger plan.
"AlmaLinux 10 needs a CPU of level x86-64-v3; node … gives its servers the CPU model …" The node's or plan's CPU model is older than the image needs. Use host-model or a newer named model on the plan, or another node.
"Node … agent cannot set up FreeBSD servers yet: update its agent" FreeBSD needs agent 0.36.0 or later.
"This node's agent does not support Windows servers yet; update the agent." Windows needs agent 0.34.0 or later.
"Image … is not on node … yet: it was made from a server and is still being copied there." Images made from a server reach other nodes over the migration port. Wait, or check that the nodes can reach each other on port 8444.
"Node … has no UEFI firmware (install the ovmf package)." / "… has no TPM emulator (install the swtpm and swtpm-tools packages)." The image's firmware needs them. On the node: apt install ovmf swtpm swtpm-tools (the node installer adds them), then wait for the panel to read the node again.
"Applications and recipes run on Linux images only." Choose a Linux image, or no application.

The server builds but cannot be reached: open its Screen console and the build log's First-boot output. An image without cloud-init (or with cloud-init disabled) never takes the network, password or keys the panel gives it.

Make an image fails#

Message Fix
"Install the libguestfs-tools package on node … to make images" On the node: apt install libguestfs-tools, then Make again.
The button is greyed out with "Shut the server down first." Shut the server down; images and clones are made only of stopped servers.
The server was installed from an ISO Tick that it is a prepared template (cloud-init installed and cleaned, or sysprepped Windows).
The capture failed after a node agent restart Press Make again on the image's row. Leftover part files are removed by the agent's next start.

Container images#

Problem Fix
image_checksum_mismatch The build's download does not match the SHA-256 in images.linuxcontainers.org's index. It is deleted; the next create downloads it again. If the image pins a build, check the Pinned build.
image_signature_invalid The build's SHA256SUMS is not signed by the LXC image key, or does not list the tarball. Do not turn the signature check off unless the image server signs nothing.
The container has no network, password or keys The product is not a cloud variant. Use the cloud variant of the distribution.
An EL 10 container image is refused on a node AlmaLinux, Rocky, CentOS Stream and Oracle Linux 10 need an x86-64-v3 CPU on the node itself.
The catalogue page says the image server could not be read The panel keeps the last copy it read. Check that the panel server reaches https://images.linuxcontainers.org, then press Refresh now.

ISO drives#

  • "ISO drives become available after this server is powered off and started once." The server was made before it had drives. Shut it down (or power it off) and start it from the panel; a reboot from inside is not enough.
  • A customer's link is refused ("the link points to a private address", "Own ISOs cannot be used on this server's host yet"): set This panel's public addresses under System › Settings › Customers' ISOs, or run install.sh --upgrade --panel-ip <address> on the node. Links to private addresses are always refused.
  • The installer does not see the disk (Windows): load the viostor driver from the VirtIO drivers ISO in CD-ROM 2.

Windows templates#

Problem Fix
A panel build stopped at Install Windows with "Nothing happened for 120 minutes" Open the build server's console. On UEFI, check the installer did not stop at its boot menu. Then Try again.
A build stopped "before sysprep" The build script failed on the step named; the build page shows the serial lines and the script's words. The build server is kept: open its console to look inside, then Try again.
Sysprep fails with 0x80073cf2 A Store app is installed for one user. C:\Windows\System32\Sysprep\Panther\setupact.log names it; remove it for all users and run sysprep again.
New servers stop at "Windows installation cannot proceed" cloudbase-init's service was Automatic at sysprep. Rebuild the template, running SetSetupComplete.cmd before sysprep (Windows templates).
C: does not fill the larger disk A partition (WinRE) sits after C:. Move WinRE into C: in the template and remove that partition.
The Administrator password stops working after a network change CreateUserPlugin or SetUserPasswordPlugin is in the template's cloudbase-init plugins=. Remove them and rebuild.
Remote Desktop does not answer behind NAT Add a port forward to port 3389.
Windows idles at high CPU Windows optimisations is off for the server or the image.

One-click applications#

The server page's Application panel names the step that failed. On the server, the full log is:

less /var/log/vmstack-first-boot.log
  • "no report from the server" after 6 hours: the server could not reach the panel to report (check its outbound HTTPS), or the install is still running.
  • Refused at create because of port forwards: the plan's Port forwards included has no room for the application's web ports behind NAT. Use a plan with more forwards.
  • Mailcow refused: it needs a public IPv4 and outbound SMTP open.