Windows terminal notes — diagnostics and fixes (detailed)

This page is written for brand-new CS1 students using Windows. It organizes common problems by scenario, explains what is happening, gives exact copy-paste fixes, and shows how to verify the fix worked. Every section links to an authoritative source.

Quick glossary

  • PATH: a list of folders Windows searches when you type a command (e.g., java). If Java’s bin folder isn’t on PATH, java looks missing.
  • JAVA_HOME: a variable pointing to your JDK installation (some tools use it).
  • Gradle wrapper: gradlew.bat on Windows — runs the project’s Gradle version (course uses Gradle 9.2.0).

Important course versions

  • Java: JDK 25 (Temurin) — follow /setup/setup-jdk/ for downloads and the correct path.
  • Gradle: use the repository’s Gradle wrapper (9.2.0 for our assignments).

Scenario A — “java not found” or wrong Java version

What you see

  • java -version prints an older version or java is not recognized.

Diagnostics

where java
java -version
echo %JAVA_HOME%

Fix — install or set JAVA_HOME (copy/paste)

  • Install Temurin 25 from Adoptium (https://adoptium.net/) and use the installer option to set JAVA_HOME and add to PATH.
  • If you installed manually, set JAVA_HOME persistently (PowerShell example):
setx JAVA_HOME "C:\\Program Files\\Eclipse Adoptium\\jdk-25"
# close and re-open your terminal and VS Code

How to tell it worked

  • java -version prints Temurin 25 and javac --version prints javac 25.

Authoritative links

  • Adoptium Temurin: https://adoptium.net/

Scenario B — Using the wrong Gradle wrapper command

What you see

  • On Windows you typed ./gradlew test and it failed, or on Git Bash gradlew.bat did not run as expected.

Plain language

  • Windows uses gradlew.bat in PowerShell and Command Prompt. In Git Bash you can run ./gradlew but the file must have Unix line endings.

Fixes (exact commands)

  • PowerShell/Command Prompt:
.\gradlew.bat test
  • Git Bash (Unix-style):
dos2unix gradlew   # ensure LF endings
chmod +x gradlew
./gradlew test

How to tell it worked

  • You see Gradle output and the Gradle version (should be 9.2.0) when you run ./gradlew --version or . gradlew.bat --version.

Scenario C — “Permission / execution policy” errors in PowerShell

What you see

  • PowerShell complains about running scripts or you get an execution policy error.

Why

  • Windows PowerShell may block some script execution depending on the execution policy. The Gradle wrapper is a .bat file, so this rarely affects it, but PS script policies can sometimes interfere with other tooling.

Quick check

Get-ExecutionPolicy -Scope CurrentUser

Recommend fix (safe for students)

  • Prefer running .\gradlew.bat in PowerShell or use Command Prompt. If you must change the policy (instructor-guided), set RemoteSigned for your user:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Scenario D — CRLF line ending problems when using Git Bash

What you see

  • ./gradlew in Git Bash errors with /usr/bin/env: 'bash\r': No such file or directory.

Fix

dos2unix gradlew
git config core.autocrlf false   # recommend adding .gitattributes instead for repo

How to tell it worked

  • ./gradlew --version runs without the bad-interpreter error.

Scenario E — Gradle download or proxy problems

What you see

  • . gradlew.bat build times out or fails to download Gradle or dependencies.

What to try

  • Run with verbose info to see the network error:
.\gradlew.bat build --info --stacktrace
  • If you’re behind a corporate proxy, add proxy settings to %USERPROFILE%\.gradle\gradle.properties (see Gradle docs). Example format is in the Gradle wrapper docs.

Scenario F — Permission errors after using Administrator / sudo-equivalent

What you see

  • Gradle files under %USERPROFILE%\.gradle are owned by Administrator or another account and your normal account can’t write to them.

Fix — safe recovery

  1. Open an elevated PowerShell as Administrator and fix ownership (example using icacls):
icacls "%USERPROFILE%\.gradle" /grant %USERNAME%:F /T
  1. Re-open a normal terminal and run: . gradlew.bat clean build.

How to tell it worked

  • Build runs and you no longer see permission denied errors.

Final checklist for Windows (step-by-step for CS1 students)

  1. Open VS Code (PowerShell recommended) and the integrated terminal (Ctrl+`).
  2. Check Java: java -version — expect Temurin 25. If not, install Temurin 25 from Adoptium: https://adoptium.net/ and set JAVA_HOME.
  3. In assignment folder run: . gradlew.bat --version — it should show Gradle 9.2.0.
  4. Run: . gradlew.bat test.

If you hit problems, find the matching scenario above and run the copy/paste commands. When in doubt, copy the exact error and post it on the course Discord with the outputs of java -version and . gradlew.bat --version.

Authoritative references

  • VS Code terminal docs: https://code.visualstudio.com/docs/editor/integrated-terminal
  • Gradle wrapper docs: https://docs.gradle.org/current/userguide/gradle_wrapper.html
  • Adoptium Temurin downloads: https://adoptium.net/