Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Homebrew: The 'brew link' step did not complete successfully

ErrorError: The 'brew link' step did not complete successfully

Short answer

brew install puts the files into the Cellar first and then links them into the Homebrew prefix. The link step fails when files already exist there, when your user cannot write to the prefix, or when the formula is keg-only. Preview with brew link --dry-run, then fix the cause named in the output.

  • Applies to Homebrew 4, macOS 15
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run the link by hand. Its output lists each file that could not be linked and why.

    brew doctor
    brew link --dry-run node
  2. 2Match what you see, then jump to its fix

    1. 1The dry run or the link names existing files such as bin/node or include/nodeFiles from an older install already sit in the prefixFix
    2. 2brew doctor complains about ownership, or the link fails on a path you cannot write toYour user cannot write to the Homebrew prefixFix
    3. 3brew --prefix shows /usr/local on an Apple Silicon Mac, or both prefixes existTwo Homebrew installs are in use (Apple Silicon and Intel)Fix
    4. 4brew info says the formula is keg-onlyA keg-only formula is not linked by designFix

What does the error look like?

  • Error: The 'brew link' step did not complete successfully

Cause 1 of 4

Files from an older install already sit in the prefix

1Check

A manual or earlier install of Node.js left files at the paths Homebrew wants to link. brew link --dry-run lists what an overwrite would delete.

brew link --overwrite --dry-run node

2Fix

Read the list. If those files are leftovers you do not need, let Homebrew replace them.

brew link --overwrite node

3Verify

The command finishes and the linked files point into the Cellar.

ls -l "$(brew --prefix)/bin/node"
node --version

Confirmed by docs.brew.sh

Did this fix it?

Cause 2 of 4

Your user cannot write to the Homebrew prefix

1Check

The shell installer needs a writable prefix, and Homebrew advises against changing ownership blindly. Find the exact path that failed and who owns it.

brew --prefix
ls -ld "$(brew --prefix)" "$(brew --prefix)/bin"

2Fix

Fix ownership of only the path that is wrong, so it matches your user, then link again. Do not recursively change the whole prefix without knowing what is wrong.

# replace /opt/homebrew/bin with the path from the error
sudo chown "$(whoami)" /opt/homebrew/bin
brew link node

3Verify

brew doctor stops reporting the ownership problem.

brew doctor

Confirmed by docs.brew.sh

Did this fix it?

Cause 3 of 4

Two Homebrew installs are in use (Apple Silicon and Intel)

1Check

An Intel terminal or a migrated Mac can leave both /usr/local and /opt/homebrew active.

arch
command -v brew
brew --prefix

2Fix

Run the Homebrew that matches your shell, normally the arm64 one under /opt/homebrew on Apple Silicon, then link again.

/opt/homebrew/bin/brew link node

3Verify

command -v brew points at the prefix you intend.

command -v brew

Confirmed by docs.brew.sh

Did this fix it?

Cause 4 of 4

A keg-only formula is not linked by design

1Check

A keg-only formula is installed only in the Cellar, not linked into the default prefix.

brew info <formula>

2Fix

Put the formula's bin folder on PATH as brew info shows. Link it only if you accept that it may shadow other software.

brew link <formula>

3Verify

The command is found from a new shell.

command -v <command>

Confirmed by docs.brew.sh

Did this fix it?

How do I stop it coming back?

  • Keep one Homebrew prefix per architecture and use the matching one.
  • Run brew doctor and read every warning before installing big formulae.
  • Remove manual installs of the same tool before using Homebrew.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.