Getting Support for Java Version Manager for Windows

🏠 Overview • 📦 Installation • 📖 Usage • 🏗️ Architecture • 🏢 Enterprise • 🔒 Locking • 🌐 Networking • 🐚 Shells • 🎯 Threat Matrix • ❓ FAQ • ⚖️ SDKMAN! Comparison • 📜 Changelog • 🛡️ Security • 🤝 Contributing • 💬 Support

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