Homebrew: The 'brew link' step did not complete successfully
Error: The 'brew link' step did not complete successfullyShort 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.
Fix it fast
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 node2Match what you see, then jump to its fix
- 1
The 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
brew doctor complains about ownership, or the link fails on a path you cannot write toYour user cannot write to the Homebrew prefixFix - 3
brew --prefix shows /usr/local on an Apple Silicon Mac, or both prefixes existTwo Homebrew installs are in use (Apple Silicon and Intel)Fix - 4
brew info says the formula is keg-onlyA keg-only formula is not linked by designFix
- 1
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 node2Fix
Read the list. If those files are leftovers you do not need, let Homebrew replace them.
brew link --overwrite node3Verify
The command finishes and the linked files point into the Cellar.
ls -l "$(brew --prefix)/bin/node"
node --versionConfirmed by docs.brew.sh
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 node3Verify
brew doctor stops reporting the ownership problem.
brew doctorConfirmed by docs.brew.sh
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 --prefix2Fix
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 node3Verify
command -v brew points at the prefix you intend.
command -v brewConfirmed by docs.brew.sh
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
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
Airflow SSHOperator stops a long script with SSH command timed out
airflow.exceptions.AirflowException: SSH command timed out
SSHOperator waits only 10 seconds for a command by default.
3 causes, each with a fixBack end
Android gets HTML instead of JSON from a PHP API
org.json.JSONException: Value <br of type java.lang.String cannot be converted to JSONObject
The response body is not JSON.
2 causes, each with a fixBack 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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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