Common installer problems and how to resolve them. If your issue isn't covered here, export the installer logs (Help → Export logs) and contact support.

The Installer Browser Tab Never Opens

Symptom: you launched vamctl.exe, the console window is open, but no browser appears.

Resolve:

1. Look at the console window — it prints a line like Listening on http://127.0.0.1:54321/.
2. Open that URL in a browser manually.
3. If the URL refuses connections, an existing vamctl may be running. Open Task Manager, end any leftover vamctl.exe processes and relaunch.

"Another Operation Is Already Running"

Symptom: starting a long operation (install, deploy, backup) returns an error saying another operation is in flight.

Resolve: the installer permits only one long-running operation at a time. Either:

• Click Reattach to view the in-progress operation, or
• Wait for the current operation to finish, then retry.

If the previous operation has obviously hung (no progress for many minutes, no log output), use Cancel on the reattached view, then retry.

Prerequisite Check Fails: "Hyper-V Is Not Enabled"

Resolve:

• Click the row to expand. The installer offers to enable Hyper-V for you — accept, and reboot when prompted.
• Or enable it manually: Server Manager → Add Roles and Features → Hyper-V, then reboot.

Prerequisite Check Fails: Virtualization Is Disabled

Symptom: the installer (or Hyper-V) reports that hardware virtualization is not available.

Resolve:

1. In Task Manager → Performance → CPU, check that Virtualization shows Enabled.
2. If it is disabled, enable it in the host BIOS/UEFI — typically Advanced → System Options → Virtualization Technology (VT-x) and Virtualization Technology for Directed I/O (VT-d) — then reboot.
3. On a nested/virtualized installer host, ensure the outer hypervisor exposes virtualization to the VM.

Podman: Machine Will Not Start

Podman is required for every installation, not just offline ones: the installer uses it to build the Talos boot images that provision the cluster nodes, and to stage offline bundles. It runs as a rootful Podman machine on WSL 2 with user-mode networking. A Windows update, a WSL update, or a reboot that left WSL half-started is the usual cause of this breaking, and the failure surfaces on the Prepare Installer step or when the cluster is created.

Symptom: the Podman row on Prepare Installer fails or hangs, or cluster creation reports that the Podman machine is unavailable.

Resolve, in this order — stop after the step that fixes it:

1. Check what the machine thinks it is doing:

   podman machine list

2. If it is stopped, start it. If it reports that it is already running while the installer disagrees, stop it first and start it again:

   podman machine stop

   podman machine start

3. Reset WSL itself. This is the single most effective step after a Windows or WSL update:

   wsl --shutdown

   wsl --update

   Then start the machine again. Note that wsl --shutdown stops every WSL distribution on the host.

4. Confirm WSL 2 is the default and the kernel is current:

   wsl --status

   wsl --set-default-version 2

5. Reboot the host. A pending Windows update that has not finished installing keeps WSL in a broken state until it does.

6. If the machine is still unusable, recreate it. This discards the machine's contents, which is safe — the installer rebuilds what it needs:

   podman machine stop

   podman machine rm

   Re-run the installer, which recreates the machine with the settings it requires.

7. If preparation still fails on the Podman row, let the installer rebuild Podman for you. See Podman: Recovery Modes.

Podman: Recovery Modes

The Podman row on Prepare Installer is a health check, not just a test. It verifies the Podman installation, rewrites containers.conf when it is wrong, realigns the Podman system connection with the running machine, and then probes the Podman API. Much of what the sections above describe by hand, the installer therefore already attempts on its own.

When the check cannot reach Podman it writes a diagnostic block to the log — the WSL distributions, the Podman machines, the Podman system connections and the raw podman info error — followed by the remediation steps to try, in order. Read it through Help → Export logs.

Choosing the Recovery Mode

One setting, Reinitialize Podman, decides how far that check may go to repair a broken installation:

• Off (the default): non-destructive recovery only. The installer starts an existing machine, repairs containers.conf and the system connection, and then stops and reports if that is not enough.
• On: destructive recovery is authorized. Once the non-destructive steps fail, the installer works through a ladder and re-tests after each rung — reset the machine (stop, remove, fresh init, start), then podman system reset --force, then uninstall and reinstall Podman through Scoop followed by another reset.

Set it in either place — it is the same value:

With the setting on, re-run the Prepare Installer step. Recovery runs as part of the Podman check, so there is nothing else to start.

Podman: Two Installations Clash

Symptom: podman behaves differently depending on which console window runs it, two console windows report different versions, the installer cannot see a machine that podman machine list shows, or the log contains:

Cause: the installer installs and manages Podman through Scoop, and recognizes its own installation by the scoop\shims folder in the resolved executable path. A Podman installed any other way — the MSI from the Podman releases page, Podman Desktop, or another package manager — counts as external. Both can be present at once, because Scoop puts its shims on the user PATH while an MSI writes to the machine PATH. Which podman.exe runs then depends on the console window: an elevated console, a console opened before the installer ran, and a console under a different account can each resolve a different binary, and therefore a different version.

An external Podman still works, but the installer treats it as hands-off:

• The installer does not update it, because it does not own the installation.
• The last step of destructive recovery is skipped, so a broken Podman must be repaired by hand.
• Both installations share the connection configuration under %APPDATA%\containers\, so a machine created by one version can be unreachable from the other.

Resolve:

1. List every podman the PATH resolves:

   Get-Command podman -All | Select-Object Source, Version

2. If more than one appears, keep the one under scoop\shims and remove the others through Settings > Apps > Installed apps. Uninstall Podman Desktop as well if it is present: it brings its own Podman.

3. Close every open console window. A window opened before the change keeps the old PATH and keeps resolving the removed binary.

4. Open a new console and confirm that only one entry remains.

5. Re-run the Prepare Installer step.

Podman: Installation Is Incomplete

Symptom: preparation fails with Podman environment verification failed. Your Podman installation may be incomplete.

Cause: the installer checks two things before it uses Podman. First, that win-sshproxy.exe is present in the Podman installation folder — it forwards the machine's API onto a Windows named pipe, so nothing reaches Podman without it. Second, that containers.conf points at the folder holding it. The installer writes that pointer itself, into %APPDATA%\containers\containers.conf:

An interrupted install or update, or a hand-edited containers.conf, breaks one of the two.

Resolve:

1. Confirm the helper binary exists. For the Scoop installation the installer manages, that is:

   Get-ChildItem "$env:UserProfile\scoop\apps\Podman\current" -Recurse -Filter win-sshproxy.exe

2. Inspect the configuration file and check that helper_binaries_dir points at the folder from step 1:

   Get-Content "$env:APPDATA\containers\containers.conf"

3. If only containers.conf is wrong, re-run the Prepare Installer step. The installer rewrites the file itself, which is non-destructive and needs no setting change.

4. If win-sshproxy.exe is missing, the Podman installation itself is damaged. Reinstall Podman: turn on Reinitialize Podman and re-run preparation, or reinstall by hand when Podman came from somewhere other than the installer. See Podman: Recovery Modes.

Podman: Networking or DNS Fails Inside the Machine

Symptom: Podman runs, but pulls fail, the registry is unreachable, or name resolution fails from inside the machine while the host itself is fine. Typically appears after a WSL update, or when a VPN client is connected.

Resolve:

1. Test resolution from inside the machine:

   podman machine ssh -- "getent hosts registry.vizrt.com"

2. Reset the WSL network stack, which is what most often fixes it:

   wsl --shutdown

   Then start the Podman machine again.

3. If a VPN is connected, disconnect it and retry. Split-tunnel and full-tunnel VPN clients frequently take over WSL's DNS. If the install must run over the VPN, reconnect it after the Podman machine is running, or set a DNS server explicitly in %UserProfile%\.wslconfig:

   [network]

   generateResolvConf = false

   and provide /etc/resolv.conf inside the machine.

4. If the installation has to run with the VPN connected throughout, turn on VPN Compatible Mode in Settings (VPNInstallation in appsettings.json). The installer then creates the Podman machine with user-mode networking, which keeps the machine reachable when a VPN client takes over the host's routes.

   User-mode networking is applied when the machine is created, so turning the setting on changes nothing about a machine that already exists. Turn it on first, then remove the machine and re-run the installer so that it recreates the machine with the setting applied:

   podman machine stop

   podman machine rm

5. If your registry uses an internal certificate authority, the CA must be trusted inside the Podman machine as well as on the host. See Registry Access.

Podman: Not Enough Memory or Disk

Symptom: the Podman machine starts, but the cluster fails to come up, or containers are killed.

On WSL2 the machine's resources come from WSL, not from podman machine set — that command reports success and changes nothing. Set them in %UserProfile%\.wslconfig:

Then apply the change and start the machine again:

Size the values against the cluster you configured, and leave the host enough memory for Windows itself. See Prerequisites → Installer Host.

Prerequisite Check Fails: "Cannot Reach Vizrt Registry"

Resolve: this is a connectivity problem from the installer host to the package registry.

1. Open a browser on the installer host and visit https://registry.vizrt.com/ (or your internal mirror).
2. If your environment uses a proxy, configure WinHTTP proxy settings: netsh winhttp set proxy <proxy>:<port>.
3. If you are air-gapped, switch the workflow to Offline installation and use a bundle prepared elsewhere.

Cluster Install Fails: "Node Did Not Become Ready"

Symptom: cluster installation completes provisioning, but one or more nodes never report Ready.

Resolve:

1. Expand the failing step in the wizard to see the live log.
2. Common causes:
   • IP conflict: the static IP you allocated is already in use. Pick a different IP and retry.
   • DNS unreachable: Talos cannot resolve the package registry. Confirm DNS works from the node's network.
   • Insufficient resources: the Hyper-V host or vSphere cluster lacks RAM/CPU for the configured node sizes.
3. After fixing the underlying issue, click Retry. The installer picks up where it left off; you should not need to restart the wizard.

Hyper-V: Virtual Switch or VM Creation Fails

Symptom: on a Hyper-V install, provisioning fails while creating the virtual switch or the node VMs.

Resolve — virtual switch:

• The public switch needs a physical network adapter facing your network. If that adapter is already bound to another virtual switch, it cannot be reused — free it, or pre-create a switch with the expected name.
• Conflicts with leftover switches from a previous attempt can block creation. Remove stale VAM switches (for example, VAMPublicSwitch, VAMPrivateSwitch, a NATSwitch) in Hyper-V Manager → Virtual Switch Manager, then retry.

Resolve — VM creation:

• Base path already in use: a folder with the VM name already exists at the deployment path. Choose a different base path or delete the leftover folder.
• IP already in use: one of the node IPs (control-plane, worker, or VIP) is taken by another machine or a VM outside the selected context. Free the IP or change it in the advanced settings.
• Disk I/O / out of space: the Hyper-V host disk is full. Point the Hyper-V base path at a disk with more free space, or free space on the current one.

Nodes: Static IP, DHCP, or DNS Problems

Symptom: nodes fail to come up, or DNS shows as invalid.

Resolve:

• If DHCP is unreliable in your environment, de-select DHCP in the wizard and provide a valid static IP, subnet and gateway per node.
• A valid, reachable DNS server is always required. If a node's configured DNS is wrong or unreachable it may show an INVALID IP in its network configuration. Confirm the DNS servers you entered are reachable from the node network.
• If the control-plane IP changed after a reboot (DHCP lease change), clients can no longer reach the API server. Give the control plane a fixed IP (DHCP reservation or static) to avoid this.

Deployment Fails on a Single Package

Symptom: cluster install succeeded, but during package deployment one package fails while others succeed.

Resolve:

1. Expand the failing package to read the error.
2. Click Skip and continue only if the failing package is optional. Required-package failures must be fixed.
3. After fixing, return to the deployment screen and click Retry — only the failed package is re-attempted, not the whole installation.

Certificate (AD CS / Enterprise CA) Deployment Fails

Symptom: deployment fails at the certificate/issuer step, with an error that the issuer resource is invalid — for example that spec.url, spec.templateName, or spec.caBundle is the wrong type, or "Error deploying Cluster Issuer".

Cause: this almost always means one of the AD CS inputs was left blank or mis-typed, so a placeholder was not substituted with a real value.

Resolve:

1. Re-open the TLS certificate step and confirm every AD CS field is filled: the ADCS server URL, the CA bundle, the certificate template name and the enrollment username / password.
2. Confirm the account can request certificates from that template on your AD CS server, and that the URL is reachable from the cluster.
3. Re-run the deployment. See Existing / native Kubernetes → Certificates for the full field list.

Sanity Check Shows "Endpoint Not Reachable"

Symptom: deployment succeeded, but the post-install sanity check reports your public hostname is unreachable.

Resolve:

• Confirm the DNS A record for your hostname points to a control- plane node IP.
• Confirm port 443 is open from your test location to that IP.
• If using Auto-generate TLS, your browser warns about the self-signed certificate — that's expected, but curl and similar tools may refuse. Test with a browser to rule TLS out.

Sign-in and Authorization

These apply when you configured an external OIDC provider (Microsoft Entra ID, Okta, Auth0, external Keycloak). The full setup is in the Identity provider setup guide; the table below maps the symptoms you are most likely to hit back to the setup step that fixes them.

Verify the live settings. After install you can review the resolved authority, token endpoint, scope and role claim in Platform → Identity in the Configuration Service. Compare them against the values table.

Registry Access

For an offline install, the wizard can fail to load packages even though you selected a bundle.

Resolve:

• Make sure the bundle was produced by the same major version of the installer you are running.
• The bundle path must be accessible to the installer host (a UNC path is fine, as long as the installer process has read access).
• If the bundle is on removable media, copy it to a local disk and point the installer at the local copy.

Inspecting the Cluster Directly

If you have kubectl access to the cluster (the installer writes a kubeconfig, or use your own for a bring-your-own cluster), these read-only checks quickly locate a failing component:

On Talos-based clusters kubectl top needs the metrics server and may report Metrics API not available — use talosctl dashboard for live node CPU/memory instead. Prefer these read-only commands; avoid editing cluster resources by hand except on Vizrt support's guidance.

Exporting Logs for Support

From any screen, use Help → Export logs. The installer creates a zip at the path it shows you, containing:

• Console output for the entire session.
• All wizard step logs.
• Cluster diagnostic output (kubectl describe, recent events).
• A redacted copy of your wizard answers.

Attach the zip to your support case. Logs do not contain your WIBU license file or your OIDC client secret.