How to Fix macOS Brew Link Error

In this tutorial, you'll learn about How to Fix macOS Brew Link Error. We cover key concepts, practical examples, and best practices.

The Problem

You install a formula and Homebrew fails to symlink it:

Error: Cannot link node
Another version is already linked: 18.0.0

Or:

Linking /opt/homebrew/Cellar/node/20.0.0...
Error: Could not symlink bin/node
Target /opt/homebrew/bin/node already exists.

Homebrew cannot create symlinks because files already exist at the target paths from a previous installation.

Quick Fix

Step 1: Unlink the old version

brew unlink node

This removes symlinks for the currently linked version.

Step 2: Link the new version

brew link node

Step 3: Force link with --overwrite

brew link --overwrite node

The --overwrite flag deletes conflicting files before creating the new symlinks. Use this when the target paths contain files from non-Homebrew sources.

Step 4: Check which files conflict

brew link --dry-run node

Dry-run mode shows which files would be linked or overwritten without making changes.

Step 5: Manually remove conflicting files

sudo rm /opt/homebrew/bin/node
brew link node

Use this when --overwrite fails due to permission issues.

Step 6: Reinstall the formula if linking persists

brew reinstall node

This reinstalls the formula from scratch, which often resolves broken link states.

Step 7: Check the keg-only status

Some formulas are "keg-only," meaning they are not symlinked by design:

brew info node

If it says "keg-only," add it to PATH manually:

echo 'export PATH="/opt/homebrew/opt/node/bin:$PATH"' >> ~/.zshrc

Step 8: Fix directory permissions

sudo chown -R $(whoami):staff /opt/homebrew
brew link node

Permission issues can prevent symlink creation.

Prevention

• Use brew upgrade instead of manually installing multiple versions.
• Unlink old versions before upgrading major versions.
• Run brew cleanup to remove old formula versions.

Common Mistakes with brew link

1. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
2. Non-exhaustive pattern matches that compile with warnings then crash at runtime
3. Misunderstanding that String is [Char] with poor performance for large text operations

These mistakes appear frequently in real-world MACOS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

DodaTech Tool Reference

Doda Browser's File Inspector can visualize symlink chains created by Homebrew, making it easy to identify broken links after a failed brew link.