Linux terminal notes — diagnostics and fixes (detailed)

This page is written for brand-new CS1 students using Linux (Ubuntu/Debian). It groups common problems by scenario, explains what is happening in plain terms, gives exact copy/paste fixes, and shows how to verify the fix worked. All fixes assume the course JDK is JDK 25 and the course uses Gradle 9.2.0 via the project wrapper.

Quick glossary

  • PATH: directories the shell searches for commands. If Java’s bin folder isn’t in PATH, java won’t be found.
  • JAVA_HOME: points to the JDK installation. Some tools prefer it.
  • Gradle wrapper: ./gradlew — runs the project’s Gradle version (9.2.0 for our assignments).

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

What you see

  • java --version shows no command or shows a version other than openjdk 25.

Diagnostics

which java
java --version
javac --version
echo $JAVA_HOME

Fix (install Temurin 25 and set JAVA_HOME)

sudo apt update
sudo apt install -y wget apt-transport-https gpg
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo gpg --dearmor -o /usr/share/keyrings/adoptium.gpg
echo "deb [signed-by=/usr/share/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/adoptium.list
sudo apt update
sudo apt install -y temurin-25-jdk

# then set JAVA_HOME (temporary)
export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java))))
export PATH="$JAVA_HOME/bin:$PATH"

Persist these by adding the export lines to ~/.bashrc or ~/.profile.

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 — “./gradlew: Permission denied” or bad interpreter (CRLF)

What you see

  • ./gradlew prints Permission denied, or an error mentioning bash\r.

Fix (make executable and fix line endings)

chmod +x gradlew
sudo apt install -y dos2unix
dos2unix gradlew
./gradlew --version

How to tell it worked

  • ls -l gradlew shows the executable bit and ./gradlew --version prints Gradle info (wrapper may download Gradle 9.2.0).

Scenario C — ownership issues after using sudo

What you see

  • Errors about writing to ~/.gradle or build/ directories.

Fix (safe recovery)

sudo chown -R $(id -u):$(id -g) ~/.gradle
sudo chown -R $(id -u):$(id -g) /path/to/project/.gradle /path/to/project/build || true
./gradlew clean build

Scenario D — first-run Gradle downloads are slow or fail (network/proxy/disk)

What you see

  • ./gradlew test shows downloading messages and is slow or reports network errors.

What to try

./gradlew test --info --stacktrace
df -h ~
du -sh ~/.gradle || true

If you are behind a proxy, add the proxy settings to ~/.gradle/gradle.properties or set HTTP_PROXY/HTTPS_PROXY environment variables. See Gradle docs for the exact property names.

Scenario E — tests require a display (headless CI issues)

If tests open GUI windows on your machine or CI, install xvfb and run tests headless:

sudo apt install -y xvfb
xvfb-run ./gradlew test

Final checklist for Linux students (step-by-step)

  1. Open VS Code integrated terminal (Ctrl+`).
  2. Run java --version — expect Temurin 25. If not, follow Scenario A.
  3. In the assignment folder run ./gradlew --version — you should see Gradle 9.2.0.
  4. Run ./gradlew test.

If you hit an error, find the matching scenario above, run the diagnostic commands, and then the suggested fix. When asking for help, include outputs of java --version, ./gradlew --version, and the exact error message.

References

  • Gradle wrapper docs: https://docs.gradle.org/current/userguide/gradle_wrapper.html
  • Adoptium Temurin: https://adoptium.net/