Skip to main content

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.

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.

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.