Mantle 2 Troubleshooting Guide

This guide outlines common issues that may occur during Mantle 2 deployment, access, provisioning, and build workflows, along with recommended corrective actions. Use this page as an initial reference when diagnosing authentication, networking, PXE, Linux/KVM, virtualization, USB, ESXi deployment, and hardware-related issues.

General Troubleshooting

Issue
After three consecutive incorrect password attempts, Mantle may temporarily lock access for 15 minutes.

Recommended action - Wait 15 minutes before attempting to log in again. - Confirm that the correct credentials are being used. - If immediate access is required, contact an administrator for assistance.

DHCP Lease Assigned Before the BIOS Process Completes

Issue
If an IP address is leased before the BIOS workflow finishes, another device on the build network, such as a laptop or test system, may be consuming the available DHCP lease.

Recommended action - Configure all build-network-connected devices with static IP addresses. - Verify that unintended devices are not connected to the build segment during deployment. - Confirm that only the intended build targets are allowed to request DHCP leases from the build container.

Interrupted Build After IPs Have Already Been Leased

Issue
If a build is interrupted after target systems have already consumed their expected IP assignments, the workflow may not restart cleanly and devices may remain in a waiting state.

Recommended action - Power cycle the affected systems before attempting another build. - Confirm that the previous deployment attempt is no longer in progress. - Restart the workflow only after the environment has been reset to a known-good state.

Deployment and Access Troubleshooting

Mantle Build Interface Not Attached in ESXi

Issue
Mantle 2 may deploy successfully in ESXi, but build-related workflows can fail if the VM only has the management interface attached and the Build interface was never added.

Recommended action - Open the Mantle 2 VM settings in the ESXi Host Client. - Confirm that a second network adapter has been added. - Verify that the second adapter is connected to the designated Build port group. - If the adapter is missing or attached to the wrong port group, correct it before attempting any build operations.

Build Port Group Not Created or Mapped Incorrectly

Issue
If the dedicated Build port group is not created, or if it is assigned to the wrong virtual switch, Mantle 2 build traffic may not reach the expected network.

Recommended action - Confirm that the Build port group exists. - Verify that it is attached to the correct virtual switch or VM network. - Use a clear name that identifies it as the Mantle build network. - Recheck the mapping any time the appliance is redeployed or moved. :contentReference[oaicite:1]{index=1}

VM Powered On Before Interface and Storage Review

Issue
Powering on the Mantle 2 appliance before validating network adapters and storage settings can result in incomplete deployment preparation and require rework.

Recommended action - Before first boot, verify the management interface mapping. - Add and validate the Build network adapter. - Review the appliance storage allocation and expand it if required. - Power on the VM only after those checks are complete. :contentReference[oaicite:2]{index=2}

Mantle 2 Not Reachable After Initial Deployment

Issue
The appliance may boot successfully but still not be reachable in a browser if the management IP address has not been configured correctly inside the guest operating system.

Recommended action - Open the VM console. - Log in locally. - Open the network settings for eth0. - Change IPv4 configuration to Manual. - Enter the correct IP address, subnet mask, gateway, and DNS values. - Toggle the interface off and back on to apply the changes. - Retry access from a browser. :contentReference[oaicite:3]{index=3}

Unable to Log In After First Boot

Issue
On first login, the default Mantle account prompts for a password change. Users may think authentication failed if they do not complete the password reset and sign in again.

Recommended action - Log in locally with the initial credentials only for first access. - Complete the password reset when prompted. - Reauthenticate with the new password before continuing configuration. :contentReference[oaicite:4]{index=4}

Browser Certificate Warning When Accessing Mantle 2

Issue
A browser may display a certificate warning during first access to Mantle 2 by IP address.

Recommended action - Confirm that the IP address is the expected Mantle system. - Continue through the browser’s advanced option to proceed. - Document this as expected first-access behavior until certificate hardening is applied. :contentReference[oaicite:5]{index=5}

Slow Initial Boot After Storage Expansion

Issue
If appliance storage is increased before first power-on, the initial boot can take longer than expected.

Recommended action - Allow extra time for first boot to complete. - Confirm there is console activity before assuming the system is stalled. - Do not restart the appliance prematurely during the initial expansion process. :contentReference[oaicite:6]{index=6}

PXE and Build Network Troubleshooting

PXE Build Does Not Start After Server Power-On

Issue
A Linux or VMware datacenter build may never begin if the target system cannot reach the PXE-facing network.

Recommended action - Confirm Mantle has connectivity to the PXE-facing interface of each target server. - Verify that the correct build NIC, VLAN, or port group is being used. - Confirm DHCP, HTTP, and any required PXE services are reachable from the target host. - Validate that the intended interface is actually selected during PXE boot.

Wrong Management vs. Build Interface Assignment

Issue
Mantle may be reachable in the web UI but unable to perform builds if the management network and build network have been mapped to the wrong interfaces.

Recommended action - Verify that the management interface is connected to the network intended for GUI and API access. - Verify that the Build interface is connected only to the PXE or build network. - Recheck interface mapping after VM cloning, migration, or redeployment.

Conflicting DHCP Services on the Build Network

Issue
Unexpected PXE behavior can occur if another DHCP service is active on the same build VLAN or VM network.

Recommended action - Confirm which platform owns DHCP for the PXE scope. - Remove or isolate any unintended DHCP services on the build network. - Retest PXE boot only after DHCP ownership is clear.

Build Starts but Never Progresses Beyond Reboot

Issue
In Enterprise Linux workflows, the operating system may install successfully, reboot, and then appear stalled because Mantle expects to reconnect over SSH to finish post-install tasks.

Recommended action - Confirm that the management IP was applied correctly during installation. - Verify that SSH is reachable on the target host after the reboot. - Confirm gateway, netmask, DNS, and management interface values were entered correctly. - Re-run only after verifying the host is reachable from Mantle on the management network.

Enterprise Linux and Kickstart Troubleshooting

Kickstart Template Renders but the Build Fails Early

Issue
The Linux build may fail if required kickstart variables are missing, mismatched, or invalid for the selected workflow.

Recommended action - Confirm that the correct platform version and kickstart template were selected. - Verify all required variables are present, including: - PXE server - netmask - gateway - DNS servers - host IP - hostname - username - password - management interface - install device - Revalidate any host-specific entries before redeploying.

Wrong Install Device Selected

Issue
If the wrong install device is provided for a Linux build, the installer may target the wrong disk or fail when multiple disks are present.

Recommended action - Confirm the correct device path for each target host before deployment. - Validate disk naming consistency across the hardware set. - Avoid reusing build data from a different server model without checking install device names.

Incorrect Management Interface Name in Linux Build

Issue
If the specified management interface name does not match the actual interface on the target host, network configuration can fail during or after installation.

Recommended action - Confirm the real interface name for each target system before launching the build. - Avoid assuming identical interface names across different server models. - Re-run only after correcting the interface name in the build form.

DNS or NTP Values Cause Post-Build Issues

Issue
Incorrect DNS or NTP values may not always stop installation, but they can break later workflow stages, certificate validation, name resolution, or automation tasks.

Recommended action - Verify that DNS resolvers are reachable from the management network. - Verify that NTP sources are valid and reachable. - Correct bad values before retrying builds that depend on hostnames, certificates, or follow-on automation.

Extra Kernel Arguments Break the Installer

Issue
Improper or stale extra kernel arguments may cause the Linux installer to behave unexpectedly on some hardware platforms.

Recommended action - Remove nonessential kernel arguments and retest with a minimal working build. - Reintroduce hardware-specific arguments only after confirming the baseline install works. - Document required kernel arguments per hardware type.

KVM and Virtualization Troubleshooting

KVM Virtualization Settings Were Not Enabled

Issue
A Linux host may complete its base OS build successfully but not be ready for virtualization because KVM-specific settings were not enabled in the workflow.

Recommended action - Confirm that virtualization settings were enabled in the build form. - Confirm the correct Linux host was selected as the KVM hypervisor. - Re-run any required post-build configuration if the base OS succeeded but virtualization was omitted.

KVM Storage Pool Fails to Initialize

Issue
Virtualization setup can fail if the defined storage pool path, owner, group, permissions, or autostart settings do not match the target host.

Recommended action - Verify the target path exists or can be created. - Confirm the owner, group, and permissions are appropriate for libvirt use. - Validate that the selected pool type matches the underlying storage method. - Review whether the pool should be active immediately and whether it should autostart.

KVM Guest Definition Is Present but the VM Is Not Created Correctly

Issue
A KVM VM may not deploy as expected if the selected VM type, configuration asset, or availability/autostart options are incomplete or inconsistent.

Recommended action - Confirm the correct VM type was selected. - Validate the VM configuration asset or JSON definition before deployment. - Review CPU, memory, and disk expectations in the referenced asset. - Confirm whether the VM is intended to be created immediately or only under certain conditions.

Linux Bridge Configuration Causes Connectivity Problems

Issue
A Linux build with virtual bridges can complete, but guest or host connectivity may fail if bridge interfaces, IPv4 method, VLAN filtering, autoconnect behavior, or STP settings were entered incorrectly.

Recommended action - Confirm that the correct interfaces were assigned to each bridge. - Verify whether the bridge should use Manual, DHCP, or Disabled addressing. - Confirm VLAN filtering matches the intended trunk or access design. - Review STP settings before deployment in networks where layer-2 loops are possible. - Validate bridge autoconnect behavior after the host reboots.

VMware Datacenter Build Troubleshooting

vCenter Deployment Fails or Host Enrollment Does Not Complete

Issue
The VMware workflow may fail after ESXi provisioning if the VCSA settings are incomplete or incorrect.

Recommended action - Verify the VCSA system name, appliance name, datacenter name, cluster name, and IP settings. - Confirm SSO user, SSO domain, SSO password, and OS password are all correct. - Verify DNS and NTP settings before deployment. - Confirm that the selected VCSA version, license, and deployment size are valid for the target environment.

VMware Hosts Never Reach Ready State

Issue
A VMware build may appear to progress but never complete if one or more hosts fail to reach the expected Ready state.

Recommended action - Expand the logs in Track Build and identify the first host that did not transition correctly. - Confirm the host management IP, gateway, DNS, VLAN, and MTU settings. - Verify that the selected PXE server and datastore values are correct. - Confirm the host completed installation and is reachable on the management network.

vSAN Configuration Fails During Build

Issue
vSAN setup can fail if the intended VMkernel adapter, datastore naming, or license selection does not match the environment design.

Recommended action - Confirm that the correct VMkernel adapter is designated for vSAN traffic. - Verify the datastore name and selected license. - Validate that the vSAN network intent was defined correctly before deployment.

VMkernel or MTU Mismatch Breaks VMware Networking

Issue
Incorrect MTU values or VMkernel network assignments can cause vMotion, management, or storage-related connectivity problems after deployment.

Recommended action - Verify the configured MTU for vmk0 and any additional VMkernel adapters. - Confirm that backing port groups and physical network paths support the same MTU. - Recheck VLAN and gateway details for each VMkernel interface before redeployment.

Post-Install OVA Deployment Fails

Issue
The main infrastructure build may complete, but post-install OVA deployment can fail if the imported appliance NICs are not mapped to the correct destination networks.

Recommended action - Confirm that the correct OVA asset was selected. - Verify every NIC-to-port-group mapping before deployment. - Recheck multi-NIC appliances carefully, especially when identical network names exist in multiple environments.

Post-Install VM Creation Fails

Issue
Post-install VM creation may fail if ISO assets, resource definitions, or network selections are incomplete.

Recommended action - Confirm the correct ISO was selected. - Validate the VM name, IP, RAM, CPU, disk sizes, and port groups. - Ensure the selected datastore and target environment can support the requested resources.

Playbooks Do Not Run After Build Completion

Issue
A build may complete successfully, but post-build automation may not run if playbooks were not selected, were ordered incorrectly, or depend on connectivity that is not yet available.

Recommended action - Confirm that playbooks were actually added to the workflow. - Verify that they are listed in the intended execution order. - Confirm that target systems are reachable from Mantle after the infrastructure build completes. - Treat playbook dependencies as part of build validation, not as a separate afterthought.

Physical Network Build Troubleshooting

Serial Port Mapped to the Wrong Device

Issue
A physical network build can apply configuration to the wrong target if the serial port mapping is incorrect or duplicated.

Recommended action - Verify each serial port mapping before deployment. - Confirm that a port is not assigned to more than one target device. - Treat incorrect port mapping as a blocking issue before any production build begins.

Device Cannot Enter the Expected Baseline State

Issue
If a device is not in a state that allows configuration-mode access, template deployment may fail or produce partial results.

Recommended action - Use the Write/Erase Network Utility first when device state is uncertain. - Confirm the correct serial port and baud rate before running the utility. - Reattempt the production template only after the baseline process completes successfully.

Required Template Variables Are Missing in a Network Build

Issue
A physical network template may upload successfully as an asset but still fail at runtime if required values were not entered in the build form.

Recommended action - Confirm the template was uploaded as the correct asset type. - Verify that all required variables are populated before deployment. - Treat template readiness and variable completeness as separate validation steps.

Build Reports Success but the Device State Is Still Wrong

Issue
A network build may complete without fatal errors while still leaving the device in an incomplete or incorrect configuration state.

Recommended action - Always review post-build scan results and captured output. - Validate the running configuration, interface state, and system messages. - Treat partial success as a failed validation until the resulting state is confirmed.

USB1 Cable Not Connected

Issue
If the required USB1 cable is not connected, BIOS or build-related workflows may not complete successfully.

Recommended action - Verify that the correct USB cable is connected. - Reseat the cable if necessary before retrying the workflow.

No Required USB Cables Connected

Issue
Missing USB cabling can prevent build operations from completing.

Recommended action - Confirm that all required USB cables are connected before starting the build. - Recheck cable placement against the expected hardware setup.

Incorrect Password Entered During Hardware-Dependent Workflow

Issue
Incorrect credentials can stop the workflow before the system reaches the expected build state.

Recommended action - Re-enter the correct credentials. - Verify the authoritative password source before retrying.

Incorrect USB Selected for Write/Erase Operations

Issue
Using the wrong USB target for Write/Erase tasks can affect the wrong device or cause the workflow to fail.

Recommended action - Confirm the intended USB device before starting the operation. - Do not proceed until device selection is verified.

Incorrect USB Selected for Network Build Operations

Issue
Using the wrong USB device during a network build can invalidate the procedure.

Recommended action - Verify the intended USB device before beginning the build. - Confirm the device selection matches the procedure being executed.

Final Notes

Most Mantle 2 issues in this category can be resolved by validating network design, confirming PXE/build reachability, verifying interface and port mappings, ensuring required template variables are complete, and reviewing post-build logs before retrying. If the issue persists after these checks, escalate to the appropriate platform, virtualization, automation, or hardware support team.