VMware VMX vs VMDK Repair: How to Diagnose, Fix, and Recover Each File Type

Virtual machines rely on two critical file types: the VMX configuration file and the VMDK virtual disk file. When either becomes corrupted or deleted, the VM may fail to start or lose access to its data. Repairing a VMX involves rebuilding configuration parameters so the hypervisor can recognize and launch the VM, while recovering a VMDK focuses on restoring the actual operating system and user data. This guide explains how to fix, rebuild, and recover VMX and VMDK files, covering practical steps, tools, and best practices to minimize downtime. By mastering these repair techniques, administrators can restore broken VMs quickly and safely.

VMware VMX vs VMDK Repair: Repairing the VMX File

Repair Path 1: Remove a Stale Lock or Temporary File

The most common cause of “Cannot open configuration file” on ESXi is not corruption but a stale .vmx~ temporary file or an orphaned .vmx.lck lock folder left behind after a crash or interrupted power event. In this case, the VMX content is intact — it’s simply blocked.

On ESXi via SSH:

1. 1. SSH to the ESXi host and navigate to the VM directory:

cd /vmfs/volumes/[datastore]/[VMname] ls -ltrah

1. 2. Identify and rename any .vmx~ file:

mv VMname.vmx~ VMname.vmx_bak

1. 3. Check for active file locks:

for file in *; do vmfsfilelockinfo -p "$file" | awk '{FS="\n"; RS=""} {print $2,$7}'; done

1. 4. Power on the VM:

vim-cmd vmsvc/power.on [vmid]

On VMware Workstation:

• Close Workstation completely.
• Terminate all vmware-vmx.exe processes in Task Manager.
• Delete the .lck folder in the VM’s directory.

Repair Path 2: Rebuild the VMX File Using an Existing VMDK (ESXi)

If the VMX file is missing or corrupted beyond parsing, the standard VMware repair method is to create a new VM and attach the existing VMDK. This is documented in Broadcom KB 341647.

1. 1. In vSphere Client, right‑click the broken VM → Remove from Inventory (do not delete files).
2. 2. Right‑click an ESXi host → New Virtual Machine → Create a new VM.
3. 3. On the Customize Hardware screen, click Add New Device → Existing Hard Disk and browse to the intact .vmdk descriptor file. Add additional VMDKs if needed.
4. 4. Complete the wizard. ESXi generates a fresh .vmx file in the VM directory.
5. 5. Power on the VM. At the “Did you move or copy this VM?” prompt, select “I Moved It” to preserve the original UUID and MAC address. Choosing “I Copied It” generates new identifiers, which can break domain‑joined configurations and licensing tied to hardware identity.

Repair Path 3: Rebuild the VMX File from vmware.log

If a vmware.log file exists in the datastore, it records the last valid hardware configuration. Broadcom KB “Rebuilding the virtual machine’s .vmx file from vmware.log” outlines how to extract this information.

• Review the log for entries detailing CPU count, memory size, controller types, and NIC settings.
• Manually reconstruct a new .vmx file using these parameters.
• This method is effective when the VMX is lost but the VMDK descriptor remains unchanged.

cd /vmfs/volumes/[datastore]/[VMname]

ls -l VMname-flat.vmdk

grep "virtualDev" VMname.vmx

vmkfstools -c [flat_file_size_in_bytes] -d thin temp.vmdk

cd "C:\Program Files (x86)\VMware\VMware Workstation"

vmkfstools --fix check /vmfs/volumes/[datastore]/[VMname]/VMname.vmdk

vmkfstools --fix check /vmfs/volumes/[datastore]/[VMname]/VMname.vmdk

chkdsk [drive letter]: /f /r

fsck -y /dev/[device]

Snapshot Chain Repair: When VMX and VMDK Damage Intersect

How Snapshot Chain Corruption Combines Both Failure Types

Snapshot chain corruption is the most destructive VMware repair scenario because it simultaneously affects both VMX and VMDK layers. In a VM with snapshots, the VMX file contains references to the entire delta chain — the base disk plus sequential delta files (VMname-000001.vmdk, VMname-000002.vmdk, etc.).

• If a VMX is rebuilt without correctly mapping the snapshot chain, all delta VMDKs become orphaned.
• If the base VMDK is modified after a delta was created, ESXi reports:
  “The parent virtual disk has been modified since the child was created” — breaking the chain and rendering all delta data inaccessible.

This dual failure means both configuration integrity (VMX references) and data integrity (VMDK deltas) are compromised.

Identifying the Full Snapshot Chain Before Any Repair

Before attempting repair on a VM with snapshots, always map the complete chain to avoid losing delta data:

1. 1. List all VMDK files in the VM directory:

ls -lah *.vmdk

1. 2. Read the .vmsd file — it stores snapshot names, UIDs, and parent‑child relationships:

cat VMname.vmsd

1. 3. Inspect each delta VMDK descriptor for the parentFileNameHint value, which points to its parent disk.
2. 4. Map the full chain from the base flat file through each delta to the current working state. Any missing link identifies the exact point of corruption.

Warning: Repairing a VMX by pointing a new VM only to the base VMDK — while ignoring active deltas — discards all changes since the last snapshot consolidation.

VMX vs VMDK Repair: Decision Framework — Which File Do You Fix First?

Start with the VMX When:

• The VM is absent from vSphere inventory.
• ESXi reports “Cannot open configuration file”.
• The VM cannot register, but the datastore shows all VMDK files intact.
• A host crash preceded the failure.

In these cases, repairing the VMX carries zero data risk because the VMDK flat file remains untouched. Always attempt VMX repair first before modifying any VMDK.

Go Directly to VMDK Repair When:

• The VM registers and powers on, but the guest OS fails to boot with disk errors.
• ESXi reports “The specified virtual disk needs repair”.
• The VMDK descriptor file is missing but the flat file is present.
• A snapshot chain error appears at power‑on.
• File system corruption is visible inside the guest OS.

In these scenarios, the problem lies with the VMDK itself — descriptor, snapshot chain, or filesystem integrity. VMX repair will not resolve the issue; direct VMDK repair or data extraction is required.

Escalate to VMFS Recovery When:

Prevention: Stopping VMX and VMDK Damage Before It Happens

Back Up VMX Files Daily — They Are Kilobytes, Not Gigabytes

VMX files are tiny — just a few kilobytes — yet they define the entire VM configuration. Backing them up takes seconds and costs nothing. A simple script that compresses and archives every .vmx file across datastores daily provides an instant recovery path for any configuration loss. Because they’re so small, VMX files are the easiest part of a VM to protect, but often the most overlooked.

Consolidate Snapshots — Long Chains Are Corruption Waiting to Happen

Snapshot delta chains longer than three levels dramatically increase the risk of corruption. Each delta adds another dependency point, and a single I/O error can break the entire chain. ESXi alerts administrators when chains exceed 100 GB for good reason — they are fragile. Consolidate snapshots regularly, not just when prompted by vSphere, to reduce the blast radius of potential failures.

Never Edit VMDK Flat Files Directly

The flat file (VMname-flat.vmdk) contains raw binary data. Any manual modification outside of VMware’s structured tools (vmkfstools, vmware-vdiskmanager, or validated recovery utilities) causes irreversible corruption. Descriptor files are text and can be safely reconstructed when missing. Flat files, however, must remain untouched — they are the single source of guest OS and user data integrity.

FAQ