Demo: installing the JDK and fixing a broken PATH
On This Lesson 11 topics
Lesson Overview
This lesson is a guided demo that puts the whole module together. You have learned where files live and why extensions matter (lesson 1), how to install and check the JDK (lesson 2), how PATH and environment variables work (lesson 3), and how to use two editors (lessons 4 and 5). Now you watch, step by step, a complete setup followed by the most common failure in the whole toolbox: a broken PATH.
The story follows a learner called Lina. She installs the JDK, proves it works, deliberately breaks PATH, reads the error, and fixes it. The demo includes a planned mistake: after fixing PATH, she tests in the old terminal and the command still fails. Only a new terminal shows the fix. You have seen the reason in lesson 3. Seeing it happen is what makes it stick.
The demo prepares you for the module lab, BEG-005-LAB1 ("Working toolbox"), which asks for screenshots of the working state, the broken state, and the fixed state. Everything you need for the lab is in this lesson, and a checklist at the end tells you what to capture.
Safety first. You will edit a system setting in this demo. Changing PATH in a graphical editor or a start-up file is reversible, but only if you write down the original value before you start. The lesson gives a session-only route that cannot damage anything, and a persistent route that needs care. If you are unsure about the persistent route on your computer, use the session-only one and say so in your lab notes.
Learning Objectives
By the end of this lesson you will be able to:
- Carry out a full JDK check: install, then
java -versionandjavac -versionin a new terminal. - Record the original
PATHbefore changing it, so that you can restore it. - Break
PATHsafely, observe the error, and read it correctly. - Restore
PATHand prove the fix in a new terminal. - Explain why the old terminal still fails after the fix.
- Produce the evidence the lab asks for: screenshots of the working, broken, and fixed states.
Written Explanation
The plan
The demo has five parts, and the lab follows the same order.
| Part | What happens | Evidence |
|---|---|---|
| 1. Working state | JDK installed, both version commands print | Screenshot 1 |
| 2. Record | Save a copy of the original PATH | A text file or note |
| 3. Break | Remove the JDK folder from PATH and open a new terminal | Screenshot 2 (the error) |
| 4. Mistake | Fix PATH but test in the old terminal, which still fails | A note |
| 5. Fix | Open a new terminal; both commands work | Screenshot 3 |
Notice that part 4 is the planned mistake. It is not a trick. It reproduces the exact situation that confuses newcomers, so that you recognize it on sight.
Part 1: The working state
Lina has installed the JDK as in lesson 2. She opens a new terminal and runs:
java -version
javac -versionBoth commands print a version, and the two numbers match. She also runs where java (Windows Command Prompt), Get-Command java (PowerShell), or which java (macOS and Linux) and notes the folder it reports. That folder is the JDK's bin directory, and it is the folder she will remove from PATH in part 3. She takes screenshot 1 of the terminal showing both versions and the folder.
Part 2: Record the original PATH
Before touching anything, Lina saves a copy of the value she is about to change. This is the habit that turns a risky change into a safe experiment.
- PowerShell:
$env:PATH -split ';' | Out-File path-before.txt - Command Prompt:
echo %PATH% > path-before.txt - Bash or Zsh:
echo "$PATH" | tr ':' '\n' > path-before.txt
The file is saved in the current folder. She opens it and checks that it has content. If she ever loses track, she can compare against this file. In the graphical editor she can also copy each entry's text to a note before editing it.
Part 3: Break PATH
There are two routes. Choose one.
Route A: the session-only route (recommended if you are unsure). The change lives only in one terminal window and disappears when you close it. It cannot damage anything, and it is allowed for the lab. It does not, however, demonstrate the "old terminal" mistake as naturally, because you fix the same window you broke. To keep the lesson, you can start a second window, as shown in part 4.
- PowerShell: put a short list in
PATHfor this window, for example$env:PATH = "C:\Windows\System32". Commands from the JDK are no longer found, though system tools still work. - Bash or Zsh: start a new shell with a reduced
PATH:env PATH=/nonexistent bash(orzsh). Inside it,javacannot be found. Typeexitto return to the original shell. (If the shell fails to findenvorbashin a very unusual setup, give the full path to them.)
Route B: the persistent route (needed for the full "old terminal" demonstration). You edit the stored value, so that new terminals start with a broken PATH.
- Windows: open the Environment Variables dialog as in lesson 3 (search the Start menu for "environment variables"). Look at the User list first. If the JDK's
binfolder is an entry in thePathof the User list, select it, choose Edit or Delete, and click OK on every dialog. If the folder is only in the System list, changing it needs administrator rights and affects every user of the computer, so use Route A instead. - macOS and Linux: if your shell's start-up file (
~/.zshrcor~/.bashrc) contains a line that adds the JDK toPATH, put a#at the start of that line to disable it, and save. If the JDK is found through a system location such as/usr/bin, there is nothing to remove, so use Route A.
After the break, Lina opens a new terminal (Route B) or uses the broken window (Route A) and runs:
java -versionThe result is one of the error messages from lesson 3:
'java' is not recognized as an internal or external command,
operable program or batch file. (Command Prompt)
bash: java: command not found (Bash)(The exact wording differs by shell and version.) She takes screenshot 2, and she reads the error aloud: the shell searched every folder on PATH and did not find a program called java. Nothing is wrong with the JDK. It is installed and untouched. Only the list of shelves changed.
She also runs where java, Get-Command java, or which java. These fail too, and that is the proof that the problem is the search, not the typing.
Part 4: The planned mistake
Now Lina fixes PATH: she restores the entry (Route B) by adding the JDK's bin folder back in the Environment Variables dialog, or by removing the # in the start-up file, then saves. She goes back to the same terminal window she was using and runs java -version again.
It still fails.
Lina does not panic and does not reinstall Java. She asks the question from lesson 3: When was this terminal opened? It was opened after she broke PATH, and before she fixed it. So it holds the broken copy. The fix is stored correctly and affects only terminals opened from now on.
For Route A, the same lesson shows up differently. Lina restores the value in the broken window (for example by pasting the original list back), and it works in that window straight away, because she changed that process's own copy. But a second terminal that she opened before the fix, with the persistent route, would still show the old state. If you used Route A, open a second window before the fix and test it, to see for yourself that each window has its own copy.
Part 5: The fix, proven
Lina opens a new terminal and runs both commands:
java -version
javac -versionBoth print versions that match the originals from part 1, and where java or which java reports the same bin folder as before. She takes screenshot 3. She compares her new PATH with path-before.txt to confirm that it is the same as at the start.
The experiment is complete: working, broken, mistaken test, fixed. If her computer is back to the original state, she can also delete the note file.
What to capture for the lab
For BEG-005-LAB1 the acceptance rule is screenshots of both states and the fix. A good set looks like this:
- Working: terminal with
java -versionandjavac -version, both with version lines. - Broken: terminal with the "not recognized" or "command not found" error for
java -version. - Fixed: a new terminal with both commands working again.
- IDE (from lesson 4): IntelliJ with the
ToolboxCheckoutput showing in the Run window. - Optional note: a sentence about the planned mistake, saying which terminal failed and why.
Each screenshot should show enough of the window to read the command and the result, and the date or the window title if your system displays it. Do not include personal information such as full folder lists that show other people's names or private files.
Examples
Example 1: The complete Windows run (simple)
This is a compact transcript of Lina's Windows run using Route B. The version numbers and folders are placeholders.
C:\> java -version
openjdk version "<version>" <date>
...
C:\> javac -version
javac <version>
C:\> where java
C:\Program Files\<vendor>\jdk-<version>\bin\java.exe
(remove the JDK bin entry from the User Path in the dialog, click OK)
(new Command Prompt)
C:\> java -version
'java' is not recognized as an internal or external command,
operable program or batch file.
(restore the entry in the dialog, click OK; go back to the SAME window)
C:\> java -version
'java' is not recognized as an internal or external command,
operable program or batch file.
(open another new Command Prompt)
C:\> java -version
openjdk version "<version>" <date>
...Read the transcript as a sequence of three windows: the working one, the one that was opened while the entry was missing, and the one that was opened after the fix. The second window is the one that fails twice. It is not a different problem. It is the same inherited copy.
Example 2: The same demo on macOS or Linux (practical)
On macOS or Linux, Omar uses the session-only route to be safe:
$ java -version
openjdk version "<version>" <date>
$ which java
/usr/lib/jvm/java-<version>-openjdk/bin/java (example path)
$ env PATH=/nonexistent bash
$ java -version
bash: java: command not found
$ exit
$ java -version
openjdk version "<version>" <date>env PATH=/nonexistent bash starts a new shell whose PATH points to a folder that does not exist, so no command from the JDK is found. Typing exit leaves that shell and returns to the original, whose PATH was never changed. This is the clean, reversible version of "a new terminal with a broken PATH". It does not show the old-window lesson, so Omar adds one more step: he opens two terminal windows, uses the persistent route in one of them with a start-up file line commented out, and compares the old and new windows.
Whichever route you use, the evidence for the lab is the same three screenshots.
Example 3: Two JDKs, wrong one first (realistic)
Mariam reaches part 1 and sees something unexpected:
java -version reports a version older than the course baseline
javac -version reports the baseline versionThe two numbers disagree, which lesson 2 said means two JDKs are in play. She runs where java and where javac (or which) and sees that they report different folders. Then she prints PATH in readable form and notices that an older JDK's bin folder comes before the new one. The order decides: the first match wins.
She fixes it by moving the baseline JDK's bin entry above the older one, or removing the old entry if she no longer needs it. She opens a new terminal, and both commands now report the same version. This is not part of the planned demo, but it shows that the same tools, PATH printed in a list and where or which, solve a second classic problem from the module.
Backend Insight
The sequence in this demo (check the tool, break one thing, read the error, fix it, prove it in a fresh session) is a miniature of how backend engineers debug environments. In a company, the broken thing is more often a deployment than a laptop: a service starts with the wrong Java, or with a missing setting, or with a different PATH than it had in testing. The questions are the same: What does this process actually see? Which program does it actually run? When was it started?
Planned failures are also a real professional practice. Teams rehearse recovery, for instance by practising a rollback, because the first time you meet a failure should not be during an emergency. What you do here, a small, safe, reversible failure with a record of the original state and a clear way back, is a tiny version of that habit.
Lastly, screenshots and notes are professional evidence. A bug report that says "it worked, then I did this, then it printed this, and a new terminal fixed it" is far more useful than "Java doesn't work". Writing the lab as a story of three states trains you to report problems in a way that others can act on.
Common Mistakes
Mistake 1: Editing PATH without saving the original
- Incorrect: deleting entries from memory and hoping to remember them.
- Correct: copy the list to a file first, and compare against it after the fix.
Mistake 2: Testing in the old terminal and concluding the fix failed
The fix is stored, and the old window holds an old copy. Open a new terminal. This is the module's third classic mistake, and the demo makes it on purpose.
Mistake 3: Replacing the whole PATH instead of removing one entry
Replacing the full value in the persistent route can break Windows or other tools. Change one entry in the graphical list. The session-only route replaces the value in one window only, so it is safe, but closing that window brings back the original.
Mistake 4: Screenshots that do not prove anything
Show the command line and its output together in each screenshot, and use a fresh window for the fix. Reinstalling Java "to fix it" hides the cause and may add a second JDK.
Exercises
Try each exercise yourself before opening the solutions.
Level A: Foundation
A1. In your own words, why does the old terminal keep failing after you fix PATH?
Show solution A1
A1. A terminal receives a copy of the environment when it starts. The old window was opened while PATH was broken, so it holds a broken copy, and a later fix applies only to terminals opened afterwards.
A2. List the three states the lab asks you to show.
Show solution A2
A2. The working state (both version commands print), the broken state (the error), and the fixed state (both commands work again in a new terminal).
A3. Why must you record the original PATH before the break?
Show solution A3
A3. So that you can restore the exact original value, compare against it after the fix, and recover if you remove the wrong entry.
Level B: Application
B1. Run parts 1 and 2 on your own machine. Write down the exact output of both version commands, the output of where java or which java, and the first three lines of your saved path-before.txt file.
Show solution B1
B1. Your output depends on your JDK. Success: both commands print versions that match each other, where or which shows a bin folder of a JDK, and path-before.txt contains the folders of your PATH, one per line.
B2. Break PATH using the route you chose. Copy the exact error message you got, and name the shell that produced it.
Show solution B2
B2. An example for Command Prompt: 'java' is not recognized as an internal or external command, operable program or batch file. An example for Bash: bash: java: command not found. Your wording may differ slightly, but it must say that the command was not found or not recognized.
B3. Complete the fix. Describe, in three sentences, what you did and how you proved that it worked.
Show solution B3
B3. Example: "I restored the JDK's bin folder to PATH with the Environment Variables dialog, then opened a new Command Prompt. In the new window java -version and javac -version printed the same versions as before, and where java reported the original folder. I also compared the printed PATH with path-before.txt and they matched." A session-only fix is described the same way, with the restored value for that window.
Level C: Challenge
C1. A classmate sends a screenshot that shows java -version failing, and writes: "I fixed PATH in the dialog but it still fails." Without seeing their computer, list the three questions you would ask, in order.
Show solution C1
C1. (1) "Did you open a new terminal after saving the change?" (the old-terminal rule). (2) "Did you click OK in every dialog, and which list did you edit, User or System, and is the entry the JDK's bin folder, not the JDK root?" (saved and correct entry). (3) "What do where java or which java and a readable PATH show in the new terminal?" (whether the entry is there, and whether another JDK comes first).
C2. Design a one-page "recovery checklist" for java: command not found, usable by someone who has not read this module. It should have at most six steps, each starting with a verb, and each answerable with a command or an observation.
Show solution C2
C2. Example: (1) Read the error and note the command name. (2) Open a new terminal and run the command again. (3) Print PATH and look for the JDK's bin folder. (4) Check that the folder exists on disk and contains java and javac. (5) Add the folder to PATH (session first, then permanently) and open another new terminal. (6) Run java -version and javac -version and check that the numbers match. Your checklist may differ, as long as each step is observable.
Mini Challenge
Run the full lab rehearsal and write a lab report of no more than one page.
- Complete parts 1 to 5 with the route you chose.
- Include the three screenshots described above, and one line under each saying what it shows.
- Add a paragraph titled "What went wrong when I tested in the old terminal", in which you explain the cause in terms of when a terminal gets its environment.
- Add a short "My toolbox" list: the JDK vendor and version, the terminal you used, and the IDE you chose.
- Add a final line that says which route you used (session-only or persistent) and why.
Check your work: every screenshot shows both the command and the output, your error message is copied exactly, and your explanation does not blame the JDK for a PATH problem.
Summary & Next Lesson
Key takeaways
- A full check is
java -versionandjavac -versionin a new terminal, with matching versions, pluswhereorwhichto see the folder. - Record the original
PATHbefore any change, and prefer a session-only change when in doubt. - "Command not found" means the shell searched
PATHand found nothing. The JDK itself is untouched. - A fix to
PATHshows up only in terminals opened afterwards. Always test in a new terminal. - Evidence for the lab is three states: working, broken, and fixed.
Next lesson
This is the last lesson of the module on the development environment. Before you move on, complete the module lab, BEG-005-LAB1 ("Working toolbox"), using your screenshots from this lesson. With a working JDK, an IDE, and a terminal habit in place, you are ready for the next module of the course.
Self-check
- Why do you save a copy of
PATHbefore changing it? - What does "command not found" for
javatell you about the JDK itself? - You fixed
PATHand the same terminal still fails. What do you do? - What should a lab screenshot of the fix show?
- Why is a session-only change a safe way to practise?
Show answers
- So that you can restore the original value and compare against it.
- Nothing is wrong with the JDK. The shell could not find
javain any folder onPATH. - Open a new terminal and test there, because the old one holds the old copy.
- The command and its result together, in a new terminal, showing both version commands working.
- It changes only one window's copy, so closing the window returns everything to normal.
References
- Microsoft Learn, about_Environment_Variables. Supports these points: environment variables are inherited by child processes at start; a change made in PowerShell affects only the current session; the persistent change is made in the Environment Variables dialog (Control Panel route) or start-up files; and
PATHseparators differ between Windows and macOS or Linux. - Oracle, javac command reference (JDK 21) and java command reference (JDK 21). Support the version commands and the fact that
-versionand--versionboth exist. - Oracle, JDK 21 installation overview. Supports the install locations and supported systems mentioned in the demo.
- Not verified on an official page: the exact wording of each shell's "not found" message, the output formats of
where,which, andGet-Command, the behaviour ofenv PATH=/nonexistent bashon every system (it is standard shell usage that I did not test in this session), and the exact menu path to the Environment Variables dialog on your Windows version. The lesson hedges these. The transcripts use placeholders for versions, vendors, and dates, and are illustrations, not captured output.
Practice
Apply this lesson with the module's lab, exercises and quiz.
Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.