Skip to content

SUPPORT.md

Latest commit

 

History

History
219 lines (180 loc) · 13.7 KB

SUPPORT.md

File metadata and controls

219 lines (180 loc) · 13.7 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 diagnostic health check in any terminal: 
    jvm doctor
# Or run automated self-healing repairs directly:
jvm doctor --fix
# Or preview pending repairs safely without mutating state:
jvm doctor --fix --dry-run
# Or generate an automated diagnostic issue bundle for GitHub issues:
jvm doctor --report
  • 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 4-part actionable remediation steps (Title, Reason:, State:, Remediation:). Running jvm doctor --fix automatically repairs broken junctions, purges legacy PATH shadows, and cleans up orphaned links.
  • 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
    • Offline Cache Bundling (.jvmcache): Export central CAS cache store on a connected machine and import on air-gapped workstations: 
      jvm cache export --bundle "D:\bundles\jdk-cache.jvmcache"
jvm cache import "D:\bundles\jdk-cache.jvmcache"
    • Enforce Fail-Closed Offline Mode (--offline): If operating on a disconnected machine or strict offline policy, pass --offline to execute local queries without network latency or timeout attempts: 
      jvm current --offline
jvm which java --offline
jvm doctor --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>.

6. "Another JVM operation is currently modifying state / Concurrency timeout"

  • Root Cause: Multiple terminal tabs or automated scripts are running mutating JVM commands concurrently, or an earlier process was forcibly closed while holding %LOCALAPPDATA%\DiamTek\JVM\state.lock.
  • Resolution:
    • JVM coordinates access via directory mutexes and auto-recovers stale locks when the owning PID has exited.
    • To bypass mutual exclusion in emergency maintenance or single-threaded CI recovery, pass --no-lock: 
      jvm clean --no-lock

7. "Need to audit lockfiles, verify signatures, or recover interrupted transactions"

  • Lockfile Integrity & Drift: Audit .jvm.lock manifest schema, platform support, and configuration drift: 
    jvm lock --check
jvm lock --diff
  • Cryptographic Provenance Verification: Audit local binary signatures, HTTPS origins, and SHA-256 digests: 
    jvm verify
  • Interrupted Transaction Recovery: View transaction logs or roll back an aborted installation safely: 
    jvm transaction show
jvm transaction rollback <id>

⚡ 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
Air-gapped workstation or strict offline policy Network access blocked by corporate perimeter jvm doctor --offline Pass --offline to execute local commands without network timeouts
Concurrency timeout / state lock error Another process crashed while holding state.lock jvm doctor JVM auto-recovers dead PIDs; use --no-lock for emergency bypass
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 doctor --fix or jvm <version>
Stale configuration file (config.json) Invalid or corrupted configuration settings jvm config get jvm config reset
Environmental delta / registry divergence Session environment differs from registry baseline jvm env --diff jvm <version> --session or jvm <version>
Interrupted / aborted installation state Installation halted mid-flight before completion jvm transaction show jvm transaction rollback <id>
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
Self-update regression / unexpected bug Latest update caused unexpected behavior jvm self-update --history jvm self-update --rollback
Build fails due to Gradle/Java mismatch Older Gradle wrapper paired with newer JDK jvm run build Switch JDK (jvm 17 or jvm 21) or upgrade wrapper
Cache disk bloat Accumulation of candidate packages in CAS jvm cache stats jvm cache dedupe or jvm cache clean
System environment uncertain / multiple conflicts General configuration drift jvm doctor jvm doctor --fix or follow remediation output

📋 Standard Diagnostic Bundle

When opening a support request or asking for assistance on Discord or GitHub, generating a pre-packaged support bundle will accelerate resolution by 10x:

# Option A: Comprehensive Support Bundle (Recommended for GitHub Issues & Discord)
jvm support
# -> Generates: jvm-support-bundle.zip containing doctor audit, environment report, and config

# Option B: Automated GitHub Issue Bundle
jvm doctor --report
# -> Generates: jvm-issue-bundle.zip

# Option C: Sanitized Text Report
jvm report
# -> Generates: jvm-report.txt (secrets, tokens, and usernames automatically redacted)

# Option D: Manual Command Telemetry
# 1. Automated all-in-one system health audit:
jvm doctor

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

# 3. Environment diff inspection against persistent registry baselines:
jvm env --diff

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

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

💬 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