Found during a fresh-VM onboarding test. Filed alongside the larger Homebrew-blocker work in #2294 — this one is purely a docs fix.
Where
start-here/installing — Note block at the top.
Severity
Minor.
What the guide says
Prerequisite: Java 21 or newer. … On macOS: brew install openjdk@21.
The "you also need to set JAVA_HOME / PATH" advice only appears in the Troubleshooting section at the bottom of the page.
What actually happens
brew install openjdk@21 prints a keg-only caveat — Homebrew does not symlink it into /opt/homebrew. The wheels wrapper script handles this internally (sets its own JAVA_HOME), so the CLI works. But anything else the user runs — java -version, an IDE looking for a JDK, mvn, gradle, etc. — still resolves to /usr/bin/java and errors with "Unable to locate a Java Runtime". A user verifying the install with java -version ends up confused.
Suggested fix
In the Note block at the top of the Installing page, add a single line after the macOS install command:
On macOS, openjdk@21 is keg-only — the wheels CLI handles this itself, but if you want to call java directly, you'll also need to add it to your PATH or set JAVA_HOME. See the Troubleshooting section.
Optionally link to a one-liner that does both:
echo 'export JAVA_HOME="$(brew --prefix openjdk@21)/libexec/openjdk.jdk/Contents/Home"' >> ~/.zshrc
echo 'export PATH="$JAVA_HOME/bin:$PATH"' >> ~/.zshrc
Source
Discovered in the same fresh-VM test that produced #2294. Original finding was tagged Minor and not blocker — moving it here as a focused docs follow-up.
Found during a fresh-VM onboarding test. Filed alongside the larger Homebrew-blocker work in #2294 — this one is purely a docs fix.
Where
start-here/installing — Note block at the top.
Severity
Minor.
What the guide says
The "you also need to set JAVA_HOME / PATH" advice only appears in the Troubleshooting section at the bottom of the page.
What actually happens
brew install openjdk@21prints akeg-onlycaveat — Homebrew does not symlink it into/opt/homebrew. Thewheelswrapper script handles this internally (sets its ownJAVA_HOME), so the CLI works. But anything else the user runs —java -version, an IDE looking for a JDK,mvn,gradle, etc. — still resolves to/usr/bin/javaand errors with "Unable to locate a Java Runtime". A user verifying the install withjava -versionends up confused.Suggested fix
In the Note block at the top of the Installing page, add a single line after the macOS install command:
Optionally link to a one-liner that does both:
Source
Discovered in the same fresh-VM test that produced #2294. Original finding was tagged Minor and not blocker — moving it here as a focused docs follow-up.