Claude Desktop “Checksum Mismatch” Error: What It Means and How to Fix It

If you’ve launched the Claude desktop app and been greeted by a cryptic message like “Failed to start Claude’s workspace” followed by a long string of hexadecimal characters reading “Checksum mismatch for rootfs.img.zst,” take a breath. Your app isn’t broken, and your computer almost certainly isn’t either. This is a fairly common local cache or download verification issue, and in most cases it can be resolved in well under twenty minutes.

This guide breaks down what the error actually means, why it happens, and walks through a real troubleshooting session step by step so you can match it against whatever you’re seeing on your own screen.

What does this error actually mean?

Let’s unpack the message piece by piece.

“Failed to start Claude’s workspace” means that when the desktop app launched, it tried to load a runtime environment called a “workspace” — and that environment failed to start.

The real substance is in the second part: “Checksum mismatch for rootfs.img.zst.” The file rootfs.img.zst is a compressed root filesystem image — essentially a self-contained, miniature operating system that the Claude desktop app depends on to run. A copy of this file lives on your local machine, and every time the app starts, it checks the file’s integrity by calculating a hash (specifically a SHA256 checksum) and comparing it against the value the app expects.

If those two values don’t match, you get a “checksum mismatch”: the file on your disk doesn’t look the way it’s supposed to, which usually means something went wrong during the download or storage process, and the app refuses to load a file it can’t trust.

In plain terms: the system image stored on your computer doesn’t match what it’s supposed to contain, so the app won’t risk starting up with it.

Why does the checksum stop matching in the first place?

A few common culprits show up again and again.

The third cause deserves extra attention, because it’s the one most likely to leave you stuck in a loop where nothing you try seems to help. The app believes it’s downloading a fresh copy, but it’s actually reading the same corrupted data from cache every single time — so the checksum comes back wrong in exactly the same way, no matter how many times you retry.

How to fix it: work through these steps in order

There’s no need to reinstall your operating system or wipe your data to deal with this. Start with the simplest fix and only move on if it doesn’t work.

Step 1: Restart the app

Always start here. Fully quit the Claude desktop app — not just close the window, but quit the process entirely from the menu bar or system tray — and reopen it.

This alone resolves the issue in some cases, since certain temporary file locks or read glitches clear up on their own after a fresh restart.

Step 2: Reinstall the workspace from inside the app

If a restart doesn’t help, look for a “Workspace” option in the app’s settings and choose “Reinstall Workspace.” This forces the app to repeat the download-and-verify process from scratch.

One caveat: if the root cause is a corrupted cache (the third reason listed above), this step might not help either — the app still thinks it’s downloading something new, when in reality it’s reading the same stale, broken file.

Step 3: Manually delete the local workspace files

If neither of the above works, the next move is to manually locate and delete the cached image file on disk, forcing a completely fresh download. The exact path depends on your operating system.

macOS

rm -rf ~/Library/Application\ Support/Claude/vm_bundles/claudevm.bundle

Windows

Remove-Item -Recurse -Force "$env:APPDATA\Claude\workspaces\"

Linux

rm -rf ~/.config/Claude/workspaces/

After deleting the files, fully quit and reopen the app rather than just closing and reopening the window. This is what actually triggers a real fresh download instead of pulling from leftover cache.

What a real-world fix looked like, start to finish

The steps above are useful in the abstract, but it helps to see an actual troubleshooting session play out. Here’s how one macOS fix unfolded.

The first move was opening the app’s data directory to see what was stored there:

cd ~/Library/Application\ Support/Claude/
ls

Among the many folders listed, two were directly relevant to the workspace and its virtual machine image: claude-code-vm and vm_bundles. The first holds version-specific configuration (folders named after version numbers like 2.1.170), while vm_bundles/claudevm.bundle is where the actual system image lives — this is the folder containing the rootfs.img.zst file referenced in the original error.

With the right folder identified, the next step was deleting it directly:

rm -rf ~/Library/Application\ Support/Claude/vm_bundles/claudevm.bundle

After restarting the app, it should have triggered a clean re-download. Instead, there was a snag: the newly created claudevm.bundle folder was only 40KB — nowhere close to the gigabyte-plus size the complete image should have. Something was still cutting the download short.

Digging further turned up the actual root cause, and it traced back to the browser engine’s HTTP caching layer. A previous, truncated download — roughly 100MB of an incomplete rootfs.img.zst — had been stored in Chromium’s cache. Every subsequent “fresh download” was actually being served from that same broken cached copy, which is exactly why the resulting hash kept coming back wrong in the same way every time. That also explains why restarting the app, or even using the in-app “Reinstall Workspace” option, hadn’t fixed anything — the app had no way of knowing it was reading corrupted data instead of pulling something new from the network.

Once that was identified, the fix came down to two things: clearing the broken cache entry, and removing a marker file named .auto_reinstall_attempted. That marker exists to prevent the app from endlessly retrying a failed auto-reinstall — but if the previous attempt had already failed once, the marker would stay stuck in a “already tried” state, blocking any further automatic recovery.

With both of those cleared, restarting the app finally kicked off a complete, successful download. Here’s roughly how that progressed:

Once the download finished, the app recalculated the SHA256 checksum of the rootfs.img.zst file and compared it against the expected value originally shown in the error message. A match confirms the file is complete and uncorrupted, and the workspace is safe to start.

In this case, both the compressed rootfs.img.zst (about 1.2GB) and the decompressed rootfs.img (about 10GB) were generated correctly, and the app wrote a .origin marker file internally to signal that installation had finished cleanly. From that point on, the error was gone for good and the app worked normally.

Frequently asked questions

Why does the error keep coming back even after multiple restarts?

If the error message shows the exact same hash value every time, it’s a strong sign that a corrupted file is sitting in local cache, and the app is reading that same broken copy instead of actually fetching anything new from the network. In that situation, simply restarting won’t help — you need to manually delete the cached files first, then restart.

Will deleting the vm_bundles or workspaces folder erase my chat history or project data?

No. The workspace image is just the underlying runtime environment the app needs to operate — it’s stored completely separately from your conversation history, account information, and project files. Deleting and re-downloading the workspace image has no effect on data you’ve already created.

I let the download finish, but I’m still getting the same error. What now?

First, check whether your network connection was stable throughout — an unreliable VPN or proxy, or a firewall on a corporate or school network, can silently cut a download short. If the network checks out but the problem persists, look at the size of the newly created claudevm.bundle folder. A healthy image is generally over a gigabyte; if the folder is suspiciously small, the download still isn’t complete, and clearing the cache and retrying again is the next move.

Does this error mean something is wrong with my hard drive?

Not necessarily. In the vast majority of cases, this is an isolated issue with a single download or a cache entry, unrelated to the health of your storage hardware. It’s only worth investigating disk health if repeated cache clears and confirmed-stable network conditions still don’t resolve the download.

How long does the whole fix usually take?

Most of the time goes into re-downloading the image file, which is typically around 1.2GB. Depending on your connection speed, that usually takes somewhere between 10 and 20 minutes. The manual steps — deleting cache files and restarting the app — take only a couple of minutes on their own.

The bottom line

A “checksum mismatch” error is, at its core, just a failed integrity check on a file that doesn’t match what the app expects it to contain. It doesn’t point to a serious flaw in the software itself — more often than not, it’s a download or local caching hiccup. Working through the troubleshooting order of restart, in-app reinstall, and then a manual cache wipe with a fresh download covers nearly every case you’re likely to run into.

If you’re dealing with this same error right now, start by locating the right folder for your operating system, then work through the steps above one at a time. Most of the time, the problem comes down to one incomplete image file — delete it, let it download again, and you should be back up and running.