When macOS Breaks Your Rust Build

Picture this,

You're making a tool that works with the Agent Client Protocol (ACP). This protocol helps code editors talk to AI coding tools. You want to test your work with Zed. You also want to add a feature to copy all the ACP logs. This will help with debugging.

You download the Zed code. You're excited to start. You run.

cargo run --package zed

You expect it to build without problems. But you get over 73 errors instead. The system can't find bindings for cli, filesystem, io, sockets, and more. The WIT parser shows this error:

error: failed to resolve directory while parsing WIT for path [/Volumes/Otter/Cache/Cargo/Home/registry/src/index.crates.io-1949cf8c6b5b557f/wasmtime-wasi-29.0.1/wit]

Caused by:
    0: failed to parse package: /Volumes/Otter/Cache/Cargo/Home/registry/src/index.crates.io-1949cf8c6b5b557f/wasmtime-wasi-29.0.1/wit
    1: failed to read file "/Volumes/Otter/Cache/Cargo/Home/registry/src/index.crates.io-1949cf8c6b5b557f/wasmtime-wasi-29.0.1/wit/._test.wit"
    2: stream did not contain valid UTF-8

The Setup That Caused the Chaos

I set up Cargo to use an external drive. This saves space on my main drive.

export CARGO_HOME="/Volumes/Otter/Cache/Cargo/Home"

(Learn more about Cargo environment variables)

Why did I do this? I bought a Mac Studio with only 500 GB of storage. This was a mistake. So I got a 2 TB external drive for Cargo and Ollama. I called it "Otter" and used ExFAT format. That's where the problem starts.

The Culprit: macOS Resource Forks

The clue was right in the error message: ._test.wit. At first, I didn't know what ._ meant. After some research, I learned it means macOS resource fork files. These are extra files that macOS creates on certain drives.

Cargo placed the wasmtime-wasi-29.0.1 package on my external drive. macOS made resource fork files for each .wit file. The WIT parser needs text files. But it found binary files instead. This broke the build.

I checked how big the problem was.

find /Volumes/Otter/Cache/Cargo/Home/registry/src/index.crates.io-1949cf8c6b5b557f/wasmtime-wasi-29.0.1/wit -name "._*" -type f

This found 42 extra files, including:

wit/._test.wit
wit/deps/cli/._command.wit
wit/deps/filesystem/._types.wit
And 39 more...

The Complete Fix

I needed to do two things:

Remove the existing resource fork files:

find /Volumes/Otter/Cache/Cargo/Home/registry/src/index.crates.io-1949cf8c6b5b557f/wasmtime-wasi-29.0.1 -name "._*" -type f -delete

Prevent macOS from creating new ones:

export COPYFILE_DISABLE=1

The build worked after running these commands.

Why This Happens

This happens because:

External drives often use different file systems.
macOS makes extra files on these drives.
Build tools don't expect these files. They try to read them as code.
Mac's own file systems handle this better. So internal drives don't have this problem.

Prevention Strategies

If you use external drives for Cargo like I do, here's how to avoid this:

1. Disable Resource Fork Creation (Recommended)

Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export COPYFILE_DISABLE=1

This stops macOS from adding hidden files to other drives. This is the best fix. It stops the problem before it starts.

2. Manual Cleanup (When Things Break)

Clean up the extra files if you cannot set COPYFILE_DISABLE=1 right away.

# For custom CARGO_HOME locations
find "$CARGO_HOME/registry/src" -name "._*" -type f -delete

Note: If you do not set COPYFILE_DISABLE=1, the system will make these files again. This is only a quick fix.

3. Consider Your Filesystem

Format external drives with APFS or Mac OS Extended to avoid this problem. But this makes them work only with Macs.

Wrapping Up

macOS resource forks are usually hidden. But they can break builds when tools find them. The fix is easy once you know what to look for. But finding the problem can be hard.

Key takeaways:

Look for files that start with ._ in error messages. These are resource forks.
External drives have this problem more often.
A simple find and delete command fixes the problem.
Clean your external drives often if you use them for coding.

Talk to you later 🐊 alligator.