Troubleshooting
javm: command not found after Unix installation
Symptom: the installer finishes, but the current shell cannot run javm.
Cause and check: install.sh puts the executable in $HOME/.local/bin without editing profiles.
command -v javm
ls -l "$HOME/.local/bin/javm"
Fix: run export PATH="$HOME/.local/bin:$PATH" for the current shell, then add the directory to the appropriate
profile if it should persist. See Verify the executable.
javm use does not change the effective Java
Symptom: javm use <selector> succeeds, but java or JAVA_HOME still points to another JDK.
Cause and check: the shell integration was not loaded, the shell was not restarted after setup, or the selected JDK is not the one being resolved.
javm which <selector>
javm current
command -v java
In PowerShell, use Get-Command java instead of command -v java. Load the integration from
Shell setup, restart the shell, and run javm use again.
shell integration is not active
Symptom: use or deactivate reports that shell integration is not active.
Cause and check: javm was invoked as a normal child process instead of through the wrapper generated by
javm init <shell>.
javm init <shell>
Apply the generated integration using the instructions for your shell in Shell setup.
Invalid or unmatched .java-version
Symptom: javm use without an argument fails, or the project version cannot be selected.
Cause and check: .java-version contains an invalid selector, is empty, or names a version that is not discovered.
cat .java-version
javm ls --details
javm use
In PowerShell, use Get-Content .java-version. Replace the file contents with a valid selector, then install or link a
matching JDK. See Selectors and ranges.
Selector has no result
Symptom: javm reports that a selector is not installed.
Cause and check: no discovered JDK matches the requested version, distribution, or range.
javm ls --details
javm ls-remote 21 --distribution temurin
Install a matching JDK, link an existing one, or make the selector more specific, for example
temurin@21 instead of 21.
An unexpected distribution is selected
Symptom: an unqualified command such as javm install 21 or javm ls-remote 21 uses a different distribution
than expected.
Cause and check: unqualified selectors use the effective java.default_distribution, which is temurin unless
changed.
javm config get java.default_distribution
javm ls-remote 21 --distribution all
Use an explicit selector such as temurin@21, or change the setting with javm config set java.default_distribution <distribution>. See Configuration.
A local JDK does not appear in javm ls
Symptom: a JDK installed outside javm is not listed or cannot be selected.
Cause and check: the installation is outside the configured discovery locations, or discovery has not been run again after the installation changed.
javm ls --details
javm discover refresh
For an external JDK at a known path, register it with javm link system@<exact-version> <path>. See
link for the expected platform layout.
javm link rejects the JDK directory
Symptom: link reports that the Java executable was not found or the path could not be inspected.
Cause and check: the argument is not the JDK root for the current operating system, or its expected Java executable is missing.
ls -l /path/to/jdk/bin/java
# macOS: ls -l /path/to/jdk/Contents/Home/bin/java
# PowerShell: Test-Path 'C:\path\to\jdk\bin\java.exe'
Pass the JDK root to javm link system@<exact-version> <path>. Check the Linux, macOS, or Windows layout in the
link reference; on macOS, pass the bundle root rather than Contents/Home.
uninstall versus unlink
Symptom: javm uninstall system@... is rejected, or a link is removed when you intended to remove a JDK.
Cause and check: uninstall removes a managed JDK; unlink removes only the reference to an external JDK.
javm ls --details
javm link system@21.0.1
Use javm uninstall <selector> for a managed JDK and javm unlink system@<version> for a linked JDK. See
Managed vs linked JDKs.
The default is not applied in a new shell
Symptom: javm default <selector> succeeds, but a new shell does not activate that JDK.
Cause and check: the shell profile is not loading javm init, a static integration was generated before the default
was configured, or the default selector has no matching JDK.
javm ls --details
javm init <shell>
Ensure the profile loads the integration, regenerate a static integration if you use one, and start a new shell. See Set a default for new shells and Shell setup.
See all commands with javm --help; use javm --debug for additional diagnostic logs.