Your computer cannot read Java

You type some words into a file. You save it. Later, the machine does things — words appear on your screen. Nothing you typed was ever a thing that could happen. It was letters. So what happened in between? Most tutorials answer "compile and run it" and move straight on. That shrug is the source of about half of all beginner confusion in Java.

We're going to take that shrug apart. There are two separate programs involved, and they fail in completely different ways. Learn to tell instantly which one is complaining at you. A whole category of mystery stops happening.

Fair warning: this chapter contains a result that looks like it proves the title wrong. I'm going to show it to you rather than hide it, because that's the interesting bit.

What you'll be able to do at the end

• Say what javac and java each do, and why one isn't enough.
• Look at an error and know instantly which of the two produced it.
• Explain why the same Java file runs on a Mac and on a Linux server, unchanged.
• Spot the "I fixed it but it's still broken" trap that catches professionals weekly.
• Tell apart two error messages that look identical and mean totally different things.

Section 1Why anything needs translating at all

Deep down, a computer's brain — the CPU, or processor, the chip that actually does the work — understands one language. Its own. And that language is astonishingly stupid. Not "hard", stupid. Its instructions are things like copy this number from here to there. Or add these two numbers. Or if this number is zero, jump to a different step. That's about the level of it.

That language is called machine code, and it isn't even letters — it's numbers. Each instruction is a pattern of on/off switches inside the chip. There is no instruction called "print", let alone "print this sentence". Printing a sentence is hundreds of those tiny steps piled up.

Now here's the awkward part. There isn't one machine language — there are many. The chip in a modern Mac speaks a different language from the chip in an older Mac. A phone's chip is different again, and so is a web server's. Same idea, different words. Machine code written for one is gibberish to the other.

So any language humans can stand to write has this problem. It has to be turned into the local machine's own language before it can run. The program that does that turning is called a compiler. And how Java solves this problem is genuinely clever. Cleverer than you'd guess. It's why Java took over the world in the 1990s. Hold that thought for two sections.

Section 2Meet the specimen, line by line

In this chapter's src/ folder there's a file called Hello.java. It is the smallest complete Java program that does anything. And we're going to spend the rest of the chapter attacking it.

/**
 * The smallest complete Java program — our specimen for dissection.
 *
 * Every word here is load-bearing, and by the end of Phase 1 you'll know
 * what each one means. For now only two things matter:
 *   - main is where the JVM starts executing
 *   - this FILE is not a program; what javac makes from it is
 */
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello, machine.");
    }
}

Thirteen lines, and you deserve to know what all of them are. Even the ones whose details wait until Phase 1.

Lines 1–8 are a comment. Anything between /* and */ is a note for humans. The tools skip it entirely — it could say anything at all and the program would behave identically. Comments are free, and this file's comment is doing real work: it tells you what to care about right now.

Line 9, public class Hello {, gives the code a name. In Java every piece of code lives inside a named container called a class. This one is called Hello. The word public means "anything is allowed to use this". The { opens a box. Everything up to the matching } on the last line belongs to Hello.

Line 10, public static void main(String[] args) {, is the starting line. When something runs your program, it looks for a chunk called exactly main and begins there. Everything before main on that line describes how it can be called. And String[] args is a slot for words you could pass in from the terminal. We don't use that slot yet. Ignore the details, remember the job: main is where the machine starts.

Line 11, System.out.println("Hello, machine.");, is the only line that does anything visible. Read it right to left. The bit in quotes is the text. println means "print this, then move to a new line". System.out is the thing being printed to — your terminal window. The semicolon at the end is a full stop. Java needs one at the end of every instruction like this.

Lines 12 and 13 are the two closing curly brackets, } and }. The first closes main, the second closes the class Hello. Curly brackets always come in pairs, and every unmatched one is an error. That's it — that's the whole program.

The happy path

Two commands. Run them in the src folder.

$ javac Hello.java
$ java Hello
Hello, machine.
$ ls
Hello.class     Hello.java

javac Hello.java is stage one: the compiler reads your text and writes out a new file. It printed nothing, which — remember Chapter 0.0 — means it worked. java Hello is stage two: the actual running. And ls shows the evidence: there are now two files where there was one.

Look hard at those two command lines, because there's a detail almost everyone gets wrong for their first week. You compiled Hello.java, with the extension. You ran Hello, without it. That's not sloppiness. javac wants a file, so you give it a file name. java wants a class, so you give it a class name. Different things, deliberately.

That new file, Hello.class, is the translated version. Try opening it in your editor. You'll get a screenful of nonsense — because it isn't text. Here are the real first 230 bytes of it. Every byte that isn't a printable letter or symbol is shown as a dot:

.......=..................java/lang/Object...<init>...()V........
........java/lang/System...out...Ljava/io/PrintStream;......Hello, machine.
................java/io/PrintStream...println...(Ljava/lang/String;)V
......Hello...Code...

Those line breaks are mine, to fit the page. The real file has no lines in it at all. Your own copy may differ by a byte or two, because different Java builds pack the file slightly differently.

Mostly rubble, with a few recognisable words poking out of it — including your sentence, sitting there in one piece. That's bytecode: a list of very small numbered instructions, plus a table of the names and text your program needs. It's a program written for a machine. Just not for your machine.

Section 3The imaginary machine

Here's the trick, and it's the best idea in Java.

javac doesn't translate your code into the language of a real chip. It translates it into the language of a machine that doesn't exist. Someone sat down and invented a processor. They decided what instructions it would have, and what its language would look like. Then they never built it. Bytecode is machine code for that invented machine.

Which sounds useless. A program for a chip nobody owns can't run anywhere. Except: you can fake the imaginary machine, in software. You write one real program, for real chips. Its entire job is to pretend to be that invented processor. It carries out those instructions faithfully.

That faking program is the JVM — the Java Virtual Machine. "Virtual" here means exactly what it means in "virtual reality": not real, but convincing enough to work in. And java, the command you typed, is the JVM. When you ran java Hello, you started up an imaginary computer, handed it Hello.class, and it got to work.

Now the payoff. Your Hello.class will run on a Mac, on a Windows laptop, and on a Linux server in a data centre. Byte for byte identical. No changes, no recompiling. It will even run on a chip that hadn't been designed when you compiled it. Every one of those machines has a JVM, and every JVM speaks the same bytecode.

Compare a compiled C program. That one was translated straight into one real machine's language. It will not run on a different kind of chip at all.

Hello, machine.

Section 4Lab 1: the result that looks like it breaks the title

Everything above says the same thing: source code gets translated first, always, no exceptions. Two files, two steps. So let's try skipping a step and watch it fail.

Predict this one properly. Write your guess down. This is the single most surprising thing in Phase 0. I'd rather you got it wrong on purpose than nodded along.

$ ls
Hello.java
$ java Hello.java
Hello, machine.
$ ls
Hello.java

Section 5Two different programs, two species of error

This is the idea the chapter exists for. There are two programs. They run at different times. They complain about different things, in different words. And a huge amount of everyday confusion is not knowing which one is talking to you.

A compile-time error comes from javac, before anything runs. It means: I could not turn this text into a program. Nothing happened, nothing ran, there is no program.

A runtime error comes from java, while your program is running. It means the program was fine as a program. Then it got itself into trouble halfway through doing its job.

Let's break each one on purpose. In your editor, change println to printn — drop the l. Save. Then compile.

$ ls -lT Hello.class
-rw-r--r--  1 you  staff  419  5 Sep 05:56:21 2026 Hello.class
$ javac Hello.java
Hello.java:11: error: cannot find symbol
        System.out.printn("Hello, machine.");
                  ^
  symbol:   method printn(String)
  location: variable out of type PrintStream
1 error
$ ls -lT Hello.class
-rw-r--r--  1 you  staff  419  5 Sep 05:56:21 2026 Hello.class

Leave the typo in. Don't fix it yet. There's something to learn from a broken source file.

$ java Hello
Hello, machine.

Section 6Lab 4: the one that bites professionals weekly

Now fix the typo — put the l back in println. While you're in there, change the message from "Hello, machine." to "Hello again.". Save the file. Check it's saved. Look at it with cat Hello.java if you like — the new message is definitely in there.

Then run the program without compiling. This is not a trick question. It is, genuinely, a thing that happens to paid developers on a weekly basis. Usually about twenty minutes before they work out what's going on.

$ grep println Hello.java
        System.out.println("Hello again.");
$ java Hello
Hello, machine.
$ ls -lT Hello.java Hello.class
-rw-r--r--  1 you  staff  419  5 Sep 05:56:21 2026 Hello.class
-rw-r--r--  1 you  staff  439  5 Sep 05:56:37 2026 Hello.java

Section 7Labs 5 and 6: two errors that look the same and aren't

These two are the most valuable thing on this page. Both print the same first line. The second line is different, and the difference still confuses people ten years into a career. Do them one after the other and read slowly.

First, delete the compiled program while keeping the source. Use rm -f Hello.class — rm means remove, and yes, this genuinely deletes a file, which is why I'm saying so. It's safe here: we can always make another one with javac.

$ rm -f Hello.class
$ java Hello
Error: Could not find or load main class Hello
Caused by: java.lang.ClassNotFoundException: Hello

Now put it back and break it a different way. Recompile with javac Hello.java, then rename the compiled file: mv Hello.class Greet.class. The name mv means move. Renaming is moving something to a new name. Then try to run Greet.

Think carefully before you guess. The file is right there. It contains a real, valid, working program that printed correctly ten seconds ago. All we changed was what it's called.

$ javac Hello.java
$ java Hello
Hello again.
$ mv Hello.class Greet.class
$ ls
Greet.class     Hello.java
$ java Greet
Error: Could not find or load main class Greet
Caused by: java.lang.NoClassDefFoundError: Greet (wrong name: Hello)

Section 8Check yourself

Section 9What broke, and what surprised you

Write this bit down somewhere, in your own words, before you move on. Especially the predictions you got wrong. Those are the valuable ones. A wrong prediction points at exactly one wrong idea in your head — and you now know which one it was.

Some questions worth answering properly:

1. Which of the six labs produced an error from javac, and which from java? Why does that split matter?
2. A colleague says "I fixed the bug but it's still broken." What's your first question, and why that one first?
3. In your own words: what does ClassNotFoundException tell you, and how is it different from NoClassDefFoundError (wrong name: …)?
4. Lab 1 looked like it proved this chapter's title wrong. What was the one piece of evidence that saved it?