VMFS Recovery™
Recover data from damaged or formatted VMFS disks or VMDK files
TRY IT FREEVer 4.28, WinBUY NOWFrom $699
Last updated:

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.

VMX vs VMDK: Understanding What Each File Does Before You Repair It

The VMX File: Configuration Blueprint, Not Data

The VMX file is a small, plain‑text configuration file that defines the virtual hardware of a VMware VM. It contains parameters such as:

  • CPU count and memory allocation
  • Network adapter type and MAC address
  • Disk controller references
  • BIOS/UEFI settings
  • VM UUID

Typically only a few kilobytes in size, the VMX file is essential for the VM to appear in inventory and power on. If it is missing or corrupt, the VM cannot start, but the VMDK data remains intact. VMX corruption is a configuration loss issue, not a data loss issue.

The VMDK File: Where All Guest Data Lives

The VMDK file is the virtual hard disk of the VM. It stores:

  • The guest operating system
  • Installed applications
  • All user data

On ESXi, each VMDK consists of two parts:

  • Descriptor file (VMname.vmdk): a small text file defining disk geometry and provisioning type.
  • Flat file (VMname-flat.vmdk): the large binary file containing actual data.

If the VMDK is damaged or its descriptor is missing, the VM may still register and attempt to boot, but the guest OS will fail with disk errors. This is a data integrity problem, far more critical than VMX corruption.

Tip: VMX vs VMDK

The Critical Distinction That Determines Your Repair Path

SymptomLikely Damaged FileData at Risk?Repair Complexity
VM missing from vSphere inventoryVMXNoLow — rebuild VMX
"Cannot open configuration file" errorVMX (or stale lock)NoLow — fix lock or rebuild
VM registers but fails to boot (guest disk error)VMDK flat fileYesMedium to High
"The specified virtual disk needs repair" errorVMDK descriptor or flatYesMedium
VM boots but data is inaccessible or missingVMDK flat fileYesHigh
Snapshot chain broken ("parent has been modified")VMDK delta chainYesHigh
VMDK descriptor missing, flat file intactVMDK descriptor onlyNo (data intact)Medium — recreate descriptor
VMFS datastore offlineBoth potentiallyYesHigh — requires VMFS recovery

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
Note: how to convert VMDK to VMX

VMware VMX vs VMDK Repair: Repairing the VMDK File

Repair Path 1: Recreate a Missing VMDK Descriptor File Using vmkfstools (ESXi)

When the descriptor file (VMname.vmdk) is missing but the flat file (VMname-flat.vmdk) is intact, the VM cannot attach the disk — but all guest data remains preserved in the flat file. The official Broadcom procedure (KB 321422) uses vmkfstools to rebuild the descriptor.

Steps:

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

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

  1. 2. Identify the exact disk size of the flat file:

ls -l VMname-flat.vmdk

  1. 3. Record the byte count precisely.
  2. 4. Identify the SCSI controller type from the VMX or logs:

grep "virtualDev" VMname.vmx

  1. 5. Common values: lsilogic, pvscsi, buslogic.
  2. 6. Create a temporary VMDK of the same size:

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

  1. 7. Replace the temporary descriptor content:
  • Delete the temp flat file: rm temp-flat.vmdk
  • Rename the temp descriptor: mv temp.vmdk VMname.vmdk
  • Edit VMname.vmdk to reference VMname-flat.vmdk in the extent description.
  1. 8. Attach the repaired VMDK and power on the VM.

Important: Always copy the flat file to a safe location before starting. Never modify the flat file itself — changes cause irreversible data loss.

Repair Path 2: Repair a Corrupt VMDK with vmware-vdiskmanager (Workstation)

VMware Workstation includes vmware-vdiskmanager, a built‑in VMDK repair utility.

Steps:

  1. 1. Open Command Prompt as Administrator.
  2. 2. Navigate to the VMware Workstation install directory:

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

  1. Run the repair command:

vmware-vdiskmanager.exe -R "C:\VMs\VMname\VMname.vmdk"

This checks and repairs descriptor metadata errors, format inconsistencies, and extent mismatches. It cannot repair flat file corruption.

Repair Path 3: Repair a Corrupt VMDK with vmkfstools (ESXi)

On ESXi, vmkfstools provides similar repair functionality for VMFS datastores.

Steps:

  1. 1. SSH to the ESXi host.
  2. 2. Run:

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

  • If errors are found:

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

This repairs descriptor errors, geometry mismatches, and snapshot chain inconsistencies. It cannot recover data lost from the flat file due to hardware failure.

Repair Path 4: Mount the VMDK as a Secondary Disk to Extract Data

If the VMDK cannot be repaired but the flat file is readable, mount it to another VM for file‑level recovery.

On ESXi:

  • Power off a healthy VM → Edit Settings → Add Existing Hard Disk → select the damaged VMDK → power on → access via guest OS.

On Workstation:

  • File → Map Virtual Disks → select the VMDK → assign a drive letter → access via Explorer.

This does not repair the VMDK but allows data extraction.

Repair Path 5: Run File System Repair Inside the Guest

If the VMDK mounts but the guest OS reports filesystem errors, corruption is inside the disk, not the VMDK format.

  • Windows guest:

chkdsk [drive letter]: /f /r

  • Linux guest:

fsck -y /dev/[device]

These tools fix filesystem‑level corruption (e.g., NTFS MFT errors, ext4 orphaned inodes). They cannot recover overwritten data.

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.

When Standard Repair Tools Fail: VMFS‑Level Recovery

When vmkfstools and vdiskmanager Cannot Reach the Data

Both vmkfstools (ESXi) and vmware‑vdiskmanager (Workstation) operate at the VMDK format layer. They repair descriptor files, metadata inconsistencies, and snapshot chain issues — but they cannot recover data when the underlying VMFS datastore itself is inaccessible.

Typical causes include:

  • Storage controller failure
  • LUN reassignment or misconfiguration
  • VMFS metadata corruption
  • Complete datastore offline status

In these cases, the data still exists on physical disks, but VMware’s native tools have no filesystem path to reach it.

Recovering VMX and VMDK Files from a Damaged VMFS Datastore with DiskInternals VMFS Recovery™

DiskInternals VMFS Recovery™ is designed specifically for VMFS‑level recovery when VMware tools cannot access the datastore. It addresses both sides of the VMware VMX vs VMDK repair problem:

VMX repair scenarios:

  • Recovers deleted VMX configuration files from VMFS volumes.
  • Restores VMX files lost during host crashes or datastore browser deletions.
  • Extracted VMX files can be re‑registered immediately in vSphere.

VMDK repair scenarios:

  • Mounts VMDK files directly without requiring a running ESXi host.
  • Reconstructs VMFS volumes with corrupted or partially overwritten metadata.
  • Recovers both VMDK flat files and descriptors deleted from live datastores.
  • Supports remote ESXi connections via IP and credentials for direct datastore scanning.

Workflow:

  1. 1. Connect DiskInternals VMFS Recovery™ to the affected VMFS volume or ESXi host.
  2. 2. Run a full scan of the datastore.
  3. 3. Locate VMX and VMDK files in the recovery browser.
  4. 4. Preview file integrity before extraction.
  5. 5. Extract recovered files to a safe local or network destination.
  6. 6. Re‑register the VM or continue with standard VMware repair procedures using the recovered files.
Fix:
  1. Repair VMware VMDK
  2. Repair flat VMDK file
  3. Repair corrupted VMDK file
  4. VMware cannot open the VMX configuration file

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:

Failure TypeFirst ToolFallback ToolData Risk
Stale VMX lock / .vmx~ fileESXi SSH — mv / rmRestart management agentsNone
Missing VMX, VMDK intactNew VM Wizard + Existing DiskRebuild from vmware.logNone
Missing VMDK descriptor, flat intactvmkfstools descriptor recreationDiskInternals VMFS Recovery™Low
Corrupt VMDK (Workstation)vmware-vdiskmanager -RMount as secondary + data extractionMedium
Corrupt VMDK (ESXi)vmkfstools --fix repairMount as secondary + data extractionMedium
Broken snapshot chainManual chain mapping + consolidationDiskInternals VMFS Recovery™High
VMFS datastore offlineESXi storage rescanDiskInternals VMFS Recovery™High
Both VMX and VMDK missing/damagedDiskInternals VMFS Recovery™Professional data recoveryHigh

Ready to get your data back?

To start recovering your data, documents, databases, images, videos, and other files, press the FREE DOWNLOAD button below to get the latest version of DiskInternals VMFS Recovery® and begin the step-by-step recovery process. You can preview all recovered files absolutely for FREE. To check the current prices, please press the Get Prices button. If you need any assistance, please feel free to contact Technical Support. The team is here to help you get your data back!

FREE DOWNLOADVer 4.28, WinBUY NOWFrom $699

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

Related articles

FREE DOWNLOADVer 4.28, WinBUY NOWFrom $699