Skip to content

SUPPORT.md

Latest commit

 

History

History
156 lines (122 loc) · 9.66 KB

SUPPORT.md

File metadata and controls

156 lines (122 loc) · 9.66 KB
Raw

Getting Support for Java Version Manager for Windows

Thank you for using Java Version Manager! We want to ensure you have the best possible experience managing JDKs and JVM tools on Windows.

🔍 Self-Service Diagnostic Triage

Before opening a support ticket, check this rapid decision tree for the most common operational scenarios:

0. "Check my entire system health automatically" (jvm doctor)

  • Action: Run the automated 7-point health check in any terminal: 
    jvm doctor
  • What it does: Automatically audits %LOCALAPPDATA% storage permissions, junction target validity, User/Machine registry synchronization, where.exe java PATH precedence, rogue Oracle javapath shadowing, and PowerShell $PROFILE hooks. If any conflicts exist, jvm doctor identifies the exact root cause and outputs direct remediation steps.
  • Exit Codes:
    • 0: All diagnostic checks passed cleanly with zero conflicts.
    • 1: One or more warnings or misconfigurations detected (remediation instructions provided in output).

1. "I switched versions, but java -version didn't change" (PATH Shadowing)

  • Root Cause: A rogue installer (e.g. older Oracle JDK MSI, Chocolatey shim, or IDE installer) forcefully injected a hardcoded path ahead of JVM in your system PATH.
  • Diagnosis: Run where.exe java in your terminal: 
    where.exe java
  • Resolution:
    • If you see C:\Program Files (x86)\Common Files\Oracle\Java\javapath\java.exe listed before %LOCALAPPDATA%\DiamTek\JVM\current\bin\java.exe:
    • Run jvm clear followed by your desired version switch (e.g., jvm 21). JVM will hunt down and scrub the phantom path from your registry.
    • Close and reopen your terminal window to refresh active process memory.

2. "I keep getting Windows UAC administrator elevation prompts"

  • Root Cause: Your active configuration is set to legacy Registry Mode instead of the default UAC-free Symlink Mode. In Registry Mode, switching JDKs requires writing to Machine-level registry (HKLM), triggering Windows Administrator elevation prompts.
  • Diagnosis: Run jvm current to check your active mode (Mode: [Registry Mode] indicates Registry Mode; [Symlink Mode] indicates Symlink Mode).
  • Resolution:
    • Via CLI: Run any switch command with --symlink: 
      jvm 21 --symlink
    • Via Interactive Menu: Launch jvm -> Navigate to Settings (3) -> Press 3 to toggle Architecture from [Registry Mode] back to [Symlink Mode] (UAC Free).

3. "Network connection failed / You appear to be offline"

  • Root Cause: Corporate firewall, SSL-intercepting proxy (e.g. Zscaler, Netskope), air-gapped network, or GitHub API rate limiting on ecosystem tool queries.
    • GitHub API Rate Limiting (Ecosystem Tools): When resolving latest versions for GitHub-backed tools (Maven, Kotlin, Scala), JVM queries GitHub APIs (60 req/hr IP limit). JVM automatically attempts a zero-quota HTTP 302 redirect fallback ([ WARNING] GitHub API Rate Limit reached. Trying redirect fallback...). If redirect fallback fails or if operating in strict CI/CD pipelines, set the GITHUB_TOKEN environment variable in your session: 
      $env:GITHUB_TOKEN = "ghp_your_personal_access_token"
    • Clean Corrupted Caches: If an earlier download was interrupted or corrupted, purge stale cache files: 
      jvm clean
    • Set Proxy Variables: JVM inherits standard environment proxies in your active session: 
      $env:HTTP_PROXY  = "http://proxy.corp.internal:8080"
$env:HTTPS_PROXY = "http://proxy.corp.internal:8080"
    • Bypass Hash Verification (Air-Gapped): If your proxy allows the binary download but blocks raw vendor hash mirrors, pass: 
      jvm install 21 --skip-checksum
    • Bring Your Own JDK (Offline): Pre-extract any zip/tarball to disk and link it locally without network access: 
      jvm link "D:\OfflineStore\jdk-21.0.2" jdk-21-offline

4. "PowerShell session switching doesn't update my current terminal"

  • Root Cause: Standard batch files executed in PowerShell run inside an isolated child cmd.exe subshell, which cannot mutate parent process memory without the PowerShell Profile wrapper hook.
  • Resolution:
    • Via CLI (Recommended): Run the dedicated profile hook installer: 
      jvm hook install
# Verify active hook status:
jvm hook status
    • Via Interactive Menu: Launch jvm -> Navigate to Settings (3) -> Select Option 2 (PowerShell Profile Hook: [INSTALL]), which injects the auto-sync wrapper function into your PowerShell profiles.
    • Via Dotfiles / Manual Setup: Open your $PROFILE (notepad $PROFILE) and paste the official function jvm { ... } wrapper block documented in the FAQ.

5. "PowerShell tab completion does not suggest commands, vendors, or versions"

  • Root Cause: The active PowerShell session has not reloaded $PROFILE after running jvm hook or install.ps1, or argument completion is not yet loaded into the shell process memory.
  • Resolution:
    • In your active terminal, reload your profile immediately: 
      . $PROFILE
    • Alternatively, close and reopen your PowerShell terminal window.
    • Verify that the hook is registered: jvm hook status. Tab completion is natively registered across all three invocation forms: jvm <Tab>, jvm.bat <Tab>, and .\jvm.bat <Tab>.

⚡ Troubleshooting Quick-Reference Table

Symptom Probable Cause Diagnostic Command Remediation Command
java -version does not change after switch Phantom Oracle path or rogue MSI shadowing in PATH where.exe java jvm clear followed by jvm <version>
Constant UAC elevation prompts Active mode set to legacy Registry Mode (HKLM) jvm current jvm <version> --symlink
PowerShell session variables not updating live PowerShell Profile auto-sync hook not installed jvm hook status jvm hook install
PowerShell tab completion not working Profile not reloaded in active shell session jvm hook status . $PROFILE or reopen terminal
Corrupted download / hash mismatch / network drop Stale extraction workspaces or cache in %TEMP% jvm doctor jvm clean
GitHub API Rate Limit reached GitHub unauthenticated 60 req/hr API quota exhausted None Automatically handled by HTTP 302 redirect fallback; set $env:GITHUB_TOKEN = "<token>" if fallback is blocked
Air-gapped / proxy hash mirror blocked Proxy allows binary download but blocks checksum jvm doctor jvm install <version> --skip-checksum
Command jvm not recognized in new terminal JVM directory missing from User PATH where.exe jvm Settings (3) → Option 1 (Install to User PATH)
Directory junction broken or points to missing JDK JDK was manually deleted from disk jvm doctor jvm link (to inspect) or jvm <version> (to re-point)
Self-updater skips: "newer local build" Local JVM_BUILD is newer than GitHub release or main branch jvm current Expected for local dev builds; use jvm self-update --force to override
Want to switch between Stable and Nightly Channel configuration set to alternative channel jvm channel jvm channel stable or jvm channel nightly
System environment uncertain / multiple conflicts General configuration drift jvm doctor Follow remediation output in jvm doctor

📋 Standard Diagnostic Bundle

When opening a support request or asking for assistance on Discord, running these diagnostic commands and attaching their output will accelerate resolution by 10x:

# 1. Automated all-in-one system health audit:
jvm doctor

# 2. Active JVM environment and configuration dashboard:
jvm current

# 3. Exact executable binary resolved by JVM:
jvm which

# 4. All java.exe binaries discovered in active PATH order:
where.exe java

# 5. Environment PATH entries filtered for Java/JVM:
($env:Path -split ';') | Where-Object { $_ -match 'Java|JVM|jdk|Oracle' }

💬 Community & Direct Maintainer Support

If self-service triage doesn't solve your issue, we are here to help:

  • Discord (Fastest Response): Reach out directly to the lead maintainer on Discord at @thehawk01.
  • Email Support: Send detailed logs and diagnostic bundles to salexey09@gmail.com.
  • GitHub Issues: Open an issue on the Bug Tracker or request enhancements via Feature Requests.

🛡️ Security Vulnerabilities

Please do not file public GitHub issues for security vulnerabilities. Review our Security Policy and report privately via GitHub Security Advisories or directly via email.

← Back to Documentation Overview