Troubleshooting WSL2 Ubuntu: Fixing Read-Only File System Due to Drive Corruption

Resolve WSL2 Ubuntu read-only file system errors caused by underlying VHDX corruption. A step-by-step guide to repair your Linux filesystem.

When your WSL2 (Windows Subsystem for Linux 2) Ubuntu distribution suddenly becomes a "read-only file system," it's a critical sign that the underlying virtual disk has suffered some form of corruption. This state prevents you from writing files, installing updates, or performing any operation that requires modifying the filesystem. As a seasoned SysAdmin, you know this necessitates immediate intervention to prevent further data loss and restore functionality. This guide will walk you through the advanced troubleshooting steps to diagnose and repair your WSL2 Ubuntu filesystem.

Symptom & Error Signature

Users typically encounter a read-only filesystem when attempting any write operation within their WSL2 Ubuntu environment. Common error messages and command outputs include:

Attempting to create a file or directory:

touch /tmp/testfile
touch: cannot touch '/tmp/testfile': Read-only file system

mkdir /home/user/new_dir
mkdir: cannot create directory '/home/user/new_dir': Read-only file system

Attempting to install or update packages:

sudo apt update
E: Could not open lock file /var/lib/apt/lists/lock - open (30: Read-only file system)
E: Unable to lock directory /var/lib/apt/lists/
E: Could not open lock file /var/lib/dpkg/lock-frontend - open (30: Read-only file system)
E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?

Checking the mount status of the root filesystem:

mount | grep " / "
/dev/sdb on / type ext4 (ro,relatime,errors=remount-ro)

Notice the ro flag, indicating read-only.

Messages in kernel logs (using dmesg):

dmesg | grep -i "read-only"
[  12.345678] EXT4-fs (dm-0): mounted filesystem with ordered data mode. Opts: (null). Detected internal corruption when checking out extents from inode 1048576, block 131072.  Re-reading inode failed. Remounting filesystem read-only

This dmesg output explicitly points to internal filesystem corruption and the kernel's response to remount it as read-only.

Root Cause Analysis

The root cause of a WSL2 Ubuntu distribution becoming read-only is almost always an underlying corruption of its virtual hard disk (VHDX) file. Here's a deeper dive:

1. VHDX File Corruption: Each WSL2 distribution operates on its own VHDX file, typically located at %LOCALAPPDATA%Packages<DistroPackageName>LocalStateext4.vhdx. This file stores the entire Linux filesystem.
2. Unexpected Shutdowns: The most common trigger for VHDX corruption is an abrupt or improper shutdown of either Windows itself or the WSL2 instance. This can happen due to:
   • Forced reboots or power outages.
   • Windows updates that restart your machine without properly shutting down WSL2.
   • Force-quitting WSL2 processes via Task Manager without wsl --shutdown.
3. Filesystem Inconsistencies: When a VHDX file is unexpectedly detached or written to, the ext4 filesystem within it can enter an inconsistent or "dirty" state. During the next boot, the Linux kernel's fsck (filesystem check) utility (or similar internal checks) detects these inconsistencies.
4. Safety Mechanism: To prevent further data loss or corruption, the Linux kernel's default behavior upon detecting a damaged filesystem is to immediately remount the root filesystem (/) in read-only mode (ro). This allows you to inspect the system but prevents any changes that could exacerbate the problem. It's a protective measure, not the problem itself, but a symptom of the underlying VHDX corruption.

Step-by-Step Resolution

To resolve this issue, we will need to access the corrupted VHDX file from the Windows host, mount it as a raw disk, and then perform a filesystem check (fsck) on the ext4 partition within it from a separate, working WSL2 environment.

1. Shut Down All WSL2 Instances

Before proceeding, it's crucial to ensure that no WSL2 distributions are running and potentially locking the VHDX file.

wsl --shutdown

Always execute wsl --shutdown from an Administrator PowerShell terminal to ensure all background processes are terminated cleanly. This command shuts down all running WSL instances.

2. Locate Your Distribution's VHDX File

You need to find the exact path to the ext4.vhdx file associated with your problematic Ubuntu distribution.

1. First, list your installed WSL2 distributions to confirm its exact name:

   wsl --list --verbose
   

   Look for the name of your Ubuntu distribution (e.g., Ubuntu-22.04).

2. The VHDX file is typically located in your user's AppDataLocal directory. The path will look something like this: C:Users%USERNAME%AppDataLocalPackages<DistroPackageName>LocalStateext4.vhdx

   To find <DistroPackageName>, it usually follows the pattern CanonicalGroupLimited.<DistroName>_79f8kdqg08pga. For instance, for Ubuntu-22.04, it might be CanonicalGroupLimited.Ubuntu22.04LTS_79f8kdqg08pga.

   Example VHDX path: C:UsersYourUsernameAppDataLocalPackagesCanonicalGroupLimited.Ubuntu22.04LTS_79f8kdqg08pgaLocalStateext4.vhdx

You can navigate to %LOCALAPPDATA%Packages in File Explorer and visually locate the folder corresponding to your Ubuntu distribution if you're unsure of the exact name.

3. Mount the Corrupted VHDX as a Bare Disk in WSL2

Now, we'll expose the VHDX file as a raw block device to the WSL subsystem. This command must be run from an Administrator PowerShell terminal.

wsl --mount <PathToYourVHDX> --bare

Example:

wsl --mount "C:UsersYourUsernameAppDataLocalPackagesCanonicalGroupLimited.Ubuntu22.04LTS_79f8kdqg08pgaLocalStateext4.vhdx" --bare

This command will output a path similar to \.PHYSICALDRIVE2. Carefully note this \.PHYSICALDRIVEX path, as you will need it for unmounting later.

4. Identify the Linux Partition and Prepare for fsck

With the VHDX mounted as a bare disk, start a new, working WSL2 instance (any instance will do, even a temporary one if your main one is read-only). If you only have one Ubuntu instance and it's corrupted, you can launch it (wsl -d Ubuntu-22.04 – replace with your distro name), as the bare-mounted disk will be visible to it.

1. Open your WSL2 terminal.

2. List block devices to identify the newly attached disk and its partition:

   lsblk
   

   You should see a new disk, likely named /dev/sdb, /dev/sdc, or similar, with a single partition (e.g., /dev/sdb1). This will correspond to the ext4 filesystem inside your VHDX.

   Example lsblk output snippet:

   NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
   sda           8:0    0  256G  0 disk
   ├─sda1        8:1    0  255G  0 part /
   └─sda2        8:2    0    1G  0 part [SWAP]
   sdb           8:16   0   20G  0 disk      <-- This is likely your mounted VHDX
   └─sdb1        8:17   0   20G  0 part
   

   In this example, /dev/sdb1 is the target partition.

3. CRITICAL STEP: Before running fsck, ensure the target partition (/dev/sdb1 in our example) is not mounted within your current WSL2 environment. Running fsck on a mounted filesystem can cause severe data corruption.

   You can check if it's mounted using mount | grep /dev/sdb1. If it returns an entry, unmount it:

   sudo umount /dev/sdb1
   

   If umount fails or says it's not mounted, that's fine.

5. Run fsck to Repair the Filesystem

Now, execute fsck (filesystem check and repair) on the identified partition. We'll use the -f flag to force a check and -y to automatically confirm any repair prompts.

sudo fsck -fy /dev/sdb1 # Replace /dev/sdb1 with your identified partition

The fsck process might take some time, depending on the size of your VHDX and the extent of the corruption. It will output messages indicating any errors found and the actions taken to repair them.

Example fsck output (snippet):

e2fsck 1.46.5 (20-Sep-2022)
/dev/sdb1: Inode 1048576, i_size is 33818368, should be 2928512.  FIXED.
/dev/sdb1: Inode 1048577, i_size is 114688, should be 8192.  FIXED.
/dev/sdb1: Unattached inode 1048578
Connect to /lost+found? yes
/dev/sdb1: ONE OR MORE FILESYSTEMS WERE MODIFIED.
/dev/sdb1: 114777/6553600 files (0.1% non-contiguous), 1943486/26214400 blocks

A successful run will indicate that errors were fixed and the filesystem is now clean.

6. Unmount the VHDX from Windows

Once fsck completes and reports a clean filesystem, return to your Administrator PowerShell terminal to unmount the VHDX. Use the \.PHYSICALDRIVEX path you noted in Step 3.

wsl --unmount <PhysicalDrivePath>
# Example: wsl --unmount \.PHYSICALDRIVE2

This command safely detaches the VHDX from the WSL subsystem.

7. Restart Your WSL2 Ubuntu Distribution and Verify

Finally, restart your original Ubuntu distribution to confirm the fix.

wsl -d <YourDistroName>
# Example: wsl -d Ubuntu-22.04

Once inside, try performing a write operation, like creating a file or installing a package:

touch /tmp/test_after_fix.txt
echo "Hello World" > /tmp/hello.txt
sudo apt update

If these commands execute without "Read-only file system" errors, your filesystem has been successfully repaired!

8. (Optional) Backup and Reinstall

If fsck reports unrecoverable errors, or if the problem recurs frequently, your VHDX might be severely corrupted. In such cases, consider backing up your data and reinstalling the distribution.

1. Export the corrupted distribution (for backup):

   wsl --export <YourDistroName> <PathToBackupFile>.tar
   # Example: wsl --export Ubuntu-22.04 D:wsl_backupsUbuntu_corrupted_backup.tar
   

   This will export your distribution's entire filesystem into a .tar file. You can then extract specific files if needed.

2. Unregister the corrupted distribution:

   wsl --unregister <YourDistroName>
   # Example: wsl --unregister Ubuntu-22.04
   

   This will permanently delete the distribution and its VHDX file. Ensure you have a backup if you need data from it.

3. Reinstall Ubuntu from the Microsoft Store or import from a clean backup:

   • If reinstalling, download Ubuntu from the Microsoft Store.
   • If importing from a clean backup:

     wsl --import <NewDistroName> <InstallLocation> <PathToCleanBackup>.tar
     # Example: wsl --import Ubuntu-Clean C:wsl_distros D:wsl_backupsUbuntu_clean_backup.tar
     

9. Prevention: Best Practices

To minimize the chances of encountering a read-only filesystem again:

• Always shut down WSL2 cleanly: Before restarting Windows, performing updates, or shutting down your PC, ensure you run wsl --shutdown from an Administrator PowerShell.
• Regular Backups: Periodically back up your WSL2 distributions using wsl --export. This provides a recovery point in case of unforeseen corruption.
• Avoid Force-Closing: Do not force-close WSL2 processes via Task Manager unless absolutely necessary and you've already attempted wsl --shutdown.

By following these steps, you should be able to recover your WSL2 Ubuntu environment from a read-only state caused by VHDX corruption, ensuring your development and hosting workflows remain uninterrupted.