The single most expensive false friend: protected does not mean what you think. In C# it means “this class and its subclasses”. In Java it means “this class, its subclasses, and everything else in the same package”. Java's protected is strictly wider than C#'s, and nothing warns you.

Java 8 is not a historical curiosity the way .NET Framework 4.8 is becoming. A large amount of running enterprise Java is still on 8, and it lacks almost everything in Part 2 of this book: no var, no records, no switch expressions, no text blocks. If you inherit a Java 8 codebase, check before you reach for a modern idiom.

JAVA_HOME matters, but not everywhere, and the difference is what causes the confusion. The mvn and gradle launcher scripts use $JAVA_HOME/bin/java when the variable is set, and fall back to whatever java is on PATH when it is not. IntelliJ and Eclipse ignore it entirely and compile against the JDK configured in the project settings, which you set inside the IDE.

That is exactly why a project can build in the IDE and fail on the command line, or compile against two different versions in the same afternoon. When the versions disagree, check both: JAVA_HOME for the terminal, and the project SDK for the IDE.

There is no mvn add. You edit pom.xml in your editor and paste the coordinates. Every Java developer does this, IntelliJ autocompletes it, and nobody finds it strange. See Maven vs csproj.

Bytecode records the Java version it was compiled for. Compile with JDK 25, run on a Java 21 runtime, and the JVM refuses to load the class with UnsupportedClassVersionError: class file version 69.0. The build and the runtime must agree; see What that error means.

Two JARs holding the same class do not conflict. One silently wins. In the diagram, billing-core-1.9.jar is never consulted, so its version of Invoice might as well not exist. If code compiled against 1.9 calls a method that 2.1 removed, you get NoSuchMethodError at runtime, far from the cause. This is what people mean by “JAR hell”, and it is why Maven's dependency resolution, covered in Maven vs csproj, matters so much.

java -jar ignores -cp. The JDK documentation is explicit that with -jar, other class path settings are ignored, and that includes the CLASSPATH environment variable. Adding -cp lib/extra.jar to a -jar command does nothing, silently. Either list the dependency in the JAR's manifest, bundle it into a fat JAR as Spring Boot does, or drop -jar and use -cp with the main class named.

The build tool is the source of truth, not the IDE. If you add a dependency to pom.xml, IntelliJ needs to re-import before it resolves: usually automatic, but the manual trigger is the refresh button in the Maven panel. A build that works in the IDE but fails on mvn clean package almost always means the IDE state drifted. Trust the command line.

Historically this(...) or super(...) had to be the very first statement, so you could not validate an argument before delegating. Java 25 finalised flexible constructor bodies Java 25, which allows statements before the constructor call as long as they do not touch the instance:

public Range(int lo, int hi) {
    if (lo > hi) throw new IllegalArgumentException("lo > hi");  // now legal
    super();
    this.lo = lo;
}

On Java 21 and earlier this does not compile. The workaround is a private static helper called inside the super(...) argument itself, as in super(requireValid(name)), which you will see in a lot of existing code.

protected is not a narrowing of public in Java the way you expect. Because it also grants package access, any class placed in the same package, including one written later, by someone else, can read a protected member without subclassing. If you want “subclasses only”, Java cannot express it. Design around it: keep the member private and expose a protected accessor whose contract you control, or use a sealed hierarchy.

Forgetting a modifier is not the same as writing private. A field with no modifier is visible to the whole package. In C# a field with no modifier is private, so the muscle memory is precisely inverted.

public class Account {
    BigDecimal balance;          // package-private! anyone in this package can write it
    private BigDecimal fee;      // what you meant
}

Packages do not nest. This is the second half of the protected trap. com.acme.sandbox and com.acme.sandbox.internal look nested in the IDE tree, but to the compiler they are two unrelated packages. A package-private member in the parent is not visible to the child package.

In C#, Acme.Sandbox.Internal can see internal members of Acme.Sandbox because they share an assembly. In Java they share nothing.

Every field in an interface is implicitly public static final. There is no way to declare instance state. Older code sometimes abuses this as a “constant interface” that classes implement purely to inherit its constants. That is a recognised anti-pattern: use a final class or an enum instead.

Parameter names are not in the compiled output by default. Reflection sees arg0, arg1 unless the class was compiled with the -parameters flag. This bites when a framework binds by parameter name. Spring needs it for some constructor injection and request binding. Spring Boot's Maven and Gradle plugins enable it for you; a hand-rolled build may not.

Captured variables must be effectively final. Java lets a lambda capture a local only if that local is never reassigned after initialisation. C# closes over the variable itself and permits mutation.

int count = 0;
list.forEach(x -> count++);      // does not compile

var count = new AtomicInteger(); // the usual workaround
list.forEach(x -> count.incrementAndGet());

Awkward, but it removes a whole class of closure-capture surprise, and it is what makes lambdas safe to hand to another thread.

Record accessors have no get prefix. A record component name is read with c.name(), not c.getName(). This breaks the JavaBean convention deliberately, and older framework versions that expected getX() could not bind records. Modern Jackson and Spring handle records natively, but a library that has not been updated since about 2021 may not.

Records are shallowly immutable. A record holding a List<String> hands out the same mutable list to every caller. Defensive copying is your job:

public record Team(String name, List<String> members) {
    public Team {
        members = List.copyOf(members);   // now genuinely immutable
    }
}

This is identical to the C# situation with a record holding a List<T>, but Java gives you List.copyOf as a one-liner in the compact constructor.

A switch on a reference type throws NullPointerException unless you write case null. This is the historical behaviour preserved for compatibility. C#'s switch expression handles null through a pattern arm and throws only if nothing matches. Always consider whether you need case null, or case null, default -> to fold it into the fallback.

var plus the diamond operator infers something useless:

var list = new ArrayList<>();     // ArrayList<Object>, almost never intended
var list = new ArrayList<String>();  // what you meant

== on strings compares references, not contents. It often appears to work because the JVM interns string literals, so "abc" == "abc" is true, while a string built at runtime compares false against an identical literal. This is the single most common beginner bug in Java, and unlike C# there is no operator overload rescuing you.

String a = "abc";
String b = new String("abc");
a == b            // false
a.equals(b)       // true
Objects.equals(a, b)   // true, and null-safe on both sides

A Java text block still processes escape sequences. That matters for regexes and Windows paths, \d in a text block is an invalid escape and will not compile, so you still write \\d. C#'s raw strings do no escape processing at all, which is why they are strictly better for regex. In Java, prefer a text block for SQL, JSON and HTML; for a regex the extra backslashes are unavoidable.

Never persist ordinal(). It is the declaration position, so inserting a constant silently renumbers everything after it, and every stored row now means something different. Persist name(), or better, an explicit code field you control. This is the enum equivalent of persisting a database identity column you do not own.

None of these compile in Java, and all of them are routine in C#:

class Box<T> {
    void bad() {
        T t = new T();                  // no, cannot instantiate T
        T[] a = new T[10];              // no, cannot create a generic array
        if (x instanceof List<String>)  // no, cannot test an erased type
        Class<T> c = T.class;           // no. T has no class literal
    }
    static int count;                   // shared across ALL Box<?>; not per T
}

If you write your own annotation and forget @Retention(RetentionPolicy.RUNTIME), it silently disappears before your framework can see it. The default is CLASS, not RUNTIME, which is the opposite of what you want almost every time.

Always write @Override. It is not required, but without it a method that was meant to override becomes a silent overload if you get the signature slightly wrong; a capitalisation, a boxed parameter, an extra argument. C#'s override keyword is mandatory and so this bug cannot exist there.

Optional is not a general-purpose nullable wrapper. The designers were explicit: it is for return types where absence is a normal outcome. Do not use it for:

• Fields; it is not Serializable and adds an allocation per instance.
• Method parameters; the caller now has to wrap, and can still pass null anyway. Use an overload.
• Collections; an empty collection already means “nothing”; never return Optional<List<T>>.

And Optional itself can be null, which is the joke that writes itself. Never return a null Optional.

orElse evaluates its argument eagerly, even when the value is present. If the default is expensive or has side effects, use orElseGet:

find(id).orElse(expensiveDefault());     // always calls expensiveDefault()
find(id).orElseGet(() -> expensiveDefault());  // only when absent

Without one of those tools wired into your build, JSpecify annotations are documentation. They will not fail a build and will not warn at compile time. If your team decides to adopt them, adopt a checker in CI at the same time or the annotations will drift out of truth within months.

IEnumerable<T> is Iterable<E>, not Iterator<E>. The parallel is exact: Iterable can be iterated repeatedly and is what for (var x : xs) accepts; Iterator is the single-use cursor, matching IEnumerator<T>. Getting these the wrong way round leads to APIs that can only be consumed once.

List.of(...) and Map.of(...) Java 9 return immutable collections that throw UnsupportedOperationException on any mutation, and reject null elements. They are not a drop-in for new ArrayList<>(). If you need to add later, wrap: new ArrayList<>(List.of(...)).

Map.of also caps out at 10 pairs; beyond that use Map.ofEntries(entry(k, v), ...).

Both languages forbid it, but Java's escape hatch differs. C# gives you no way out except iterating a copy. Java's Iterator supports remove(), and there is removeIf:

// throws ConcurrentModificationException
for (var s : list) if (s.isBlank()) list.remove(s);

// correct, removeIf is the idiomatic answer
list.removeIf(String::isBlank);

// correct, explicit iterator
var it = list.iterator();
while (it.hasNext()) if (it.next().isBlank()) it.remove();

The boxed-integer cache. The JVM caches Integer objects for values from −128 to 127, so == appears to work on small numbers and silently stops working above 127. This is the single most notorious Java gotcha:

Integer a = 127, b = 127;
a == b        // true: same cached instance

Integer c = 128, d = 128;
c == d        // false; two distinct objects

c.equals(d)   // true, always use this

The same trap exists for Long, Short, Byte and Character. Any test that passes with small fixtures and fails in production is worth checking for this.

The last rule is the one that breaks systems. Two objects that are equals but hash differently will both be stored in a HashSet, and a HashMap.get with an equal key will return null. The failure is silent, data dependent, and often only shows under load when the map resizes.

A stream is a pipeline over a source, consumed exactly once. This is the difference that actually bites when translating LINQ.

var s = customers.stream().filter(c -> c.active());

var a = s.toList();
var b = s.toList();   // IllegalStateException: stream has already been operated upon

In C# the equivalent IEnumerable would simply re-run the query. In Java, either re-create the stream, or materialise once into a List and reuse that.

Collectors.toMap throws IllegalStateException on a duplicate key, where LINQ's ToDictionary throws too, but Java also throws NullPointerException if a value is null, which ToDictionary tolerates. Supply the three-argument form with a merge function whenever duplicates are possible.

parallelStream() looks like AsParallel() and is more dangerous. It runs on the shared common ForkJoinPool, so one slow parallel stream can starve every other one in the JVM, including ones inside libraries. It also only pays off for large, CPU-bound, easily-split sources.

Rules of thumb: do not use it for I/O (use virtual threads, see Threads are cheap now), do not use it on LinkedList or Iterator-backed sources, and measure before and after. For anything with a deadline, submit to your own pool instead.

Files.lines, Files.walk and Files.list return a Stream that holds an open file handle. Unlike File.ReadLines in .NET, the stream will not release it for you, and on Windows the file stays locked. They must go in a try-with-resources:

// leaks a file handle
long n = Files.lines(p).filter(l -> !l.isBlank()).count();

// correct
try (var lines = Files.lines(p)) {
    long n = lines.filter(l -> !l.isBlank()).count();
}

This is the single most common Java file-handling bug, and it usually shows up as “too many open files” under load rather than as an obvious failure.

Virtual threads do nothing for CPU-bound work. They make waiting cheap, not computing. A million virtual threads doing matrix multiplication will run exactly as fast as the number of carrier threads allows, plus scheduling overhead.

For CPU-bound work, keep a bounded platform-thread pool sized near your core count, the same instinct you already have from Parallel.For.

Never pool virtual threads. Pooling exists to amortise the cost of creating a thread. Virtual threads are so cheap to create that pooling them adds contention and reintroduces the queueing the design removes. newVirtualThreadPerTaskExecutor() allocates a new one per task on purpose.

If you need to limit concurrency, say, to protect a database with 20 connections, that is a Semaphore, not a pool. Limit the resource, not the thread count.

ThreadLocal still works, but scales badly. One ThreadLocal value per thread was fine at 200 threads. At 500,000 it is a memory problem. Use ScopedValue Java 25 instead; it is the closer analogue to AsyncLocal<T> anyway, being immutable and bounded to a well-defined scope rather than living until the thread dies.

Structured concurrency requires --enable-preview at both compile and run time. Class files built with preview features will not load on a different JDK version. Anything you find in a blog post from 2023 or 2024 uses an older API shape, new StructuredTaskScope<>() and ShutdownOnFailure; that no longer matches Java 25.

Catching InterruptedException clears the interrupt flag. If you swallow it without calling Thread.currentThread().interrupt(), every layer above you loses the cancellation signal and the thread keeps working. This is the Java equivalent of catching OperationCanceledException and ignoring it, and it is much easier to do by accident.

Either restore the flag and return, or let the exception propagate. Never just log it.

This pattern does not cancel the sibling when one task fails, close() waits for the other to finish rather than interrupting it. If fail-fast cancellation matters, call b.cancel(true) in a catch, or use invokeAny/invokeAll which have their own semantics. This gap is precisely what structured concurrency exists to close.

Never synchronized on this or on a public field. Any external code holding a reference to your object can lock on it too, and now your class's correctness depends on strangers. Use a private final lock object. The same advice applies to lock(this) in C#, and for the same reason, but Java's synchronized method modifier makes the mistake much easier to make by accident.

computeIfAbsent holds a bin lock while the mapping function runs. Calling back into the same map from inside that function, even indirectly, can deadlock or throw IllegalStateException. Keep the function short and self-contained. The same warning applies to ConcurrentDictionary.GetOrAdd, except that .NET may run the factory more than once, where Java guarantees at most once.

Do not adopt WebFlux for throughput on a new Boot service. That decision made sense in 2018 and is usually wrong now. It costs you readable stack traces, ordinary debugging, a large chunk of the blocking library ecosystem, and a much steeper learning curve for every future maintainer, in exchange for a scalability property that Spring MVC on virtual threads already has.

== compares references for every reference type, including String. It appears to work because literals are interned, then fails on a string built at runtime. Use .equals(), or Objects.equals(a, b) when either side may be null. See Equality and hashing.

Integer a = 127, b = 127; a == b is true. Integer a = 128, b = 128; a == b is false. Boxed integers from −128 to 127 are cached. Tests pass, production fails.

A null Integer unboxes to an NPE, at a line that contains no visible method call:

Map<String, Integer> counts = new HashMap<>();
int n = counts.get("missing");     // NullPointerException, not 0

In C#, int? n = dict["missing"] would be a KeyNotFoundException, a clearer failure. Use getOrDefault(k, 0).

In C# a member with no access modifier is private. In Java it is visible to the entire package. Inverted muscle memory, silent consequence. See Access modifiers and packages.

Java's protected grants access to the whole package as well as subclasses. There is no way to express C#'s subclass-only protected.

C# opts in with virtual; Java opts out with final. Any public method you write is an extension point unless you say otherwise, which matters most when you call an overridable method from a constructor, and the subclass override runs before the subclass's fields are initialised.

class Base {
    Base() { init(); }              // calls the override...
    void init() { }
}
class Child extends Base {
    private final String name = "x";
    @Override void init() {
        System.out.println(name);   // prints null, field not yet assigned
    }
}

Both languages made this mistake, and both throw at runtime rather than compile time:

Object[] objects = new String[2];
objects[0] = 42;         // compiles; throws ArrayStoreException at runtime

Generics are invariant precisely to avoid this, which is why List<String> is not a List<Object>.

A C# nested class is always independent. In Java, a nested class is only independent if you write static. A non-static inner class holds a hidden reference to the enclosing instance, which means it cannot be constructed without one, and it keeps the outer object alive.

class Outer {
    class Inner { }           // holds an implicit Outer.this
    static class Nested { }   // independent, what C# gives you by default
}

new Outer().new Inner();      // the bizarre syntax this forces
new Outer.Nested();           // normal

Default to static on every nested class unless you deliberately want the outer reference. Forgetting it is a common memory-leak source, especially for listeners and callbacks.

5 / 2 is 2 in both languages. But Java has no checked block: integer overflow always wraps silently, and there is no way to opt into throwing. Use Math.addExact, multiplyExact and friends when overflow would be a correctness bug; they throw ArithmeticException.

Java also has no unsigned types. There is no uint or ulong; use the static helpers Integer.divideUnsigned, Long.compareUnsigned and so on.

This is the one that generates the most swearing. A lambda passed to map cannot throw a checked exception, because Function's method does not declare one:

files.stream()
     .map(f -> Files.readString(f))   // does not compile: IOException
     .toList();

You must wrap it, which is ugly and universal:

.map(f -> {
    try { return Files.readString(f); }
    catch (IOException e) { throw new UncheckedIOException(e); }
})

See Exceptions and resources.

switch (s) where s is a null String or enum throws NullPointerException unless you write case null Java 21. C# handles null through a pattern arm.

java.util.Date is mutable, Calendar months are zero-based, and SimpleDateFormat is not thread-safe; a shared static instance produces silently wrong dates under concurrency. Use java.time exclusively. See Numbers, money and time.

Java has no 128-bit decimal primitive. Money is BigDecimal, which is an object with no operator overloading, so arithmetic becomes method calls and comparison becomes compareTo. Using double for money is the single most common correctness bug a C# developer introduces into Java.

subList, keySet, values, entrySet, Arrays.asList and reversed() all return views backed by the original. Mutating the view mutates the source, and mutating the source can invalidate the view.

var fixed = Arrays.asList(1, 2, 3);
fixed.set(0, 9);     // fine, writes through to the array
fixed.add(4);        // UnsupportedOperationException, fixed size

A return or throw inside finally discards whatever was propagating from try or catch, silently. C# forbids returning from a finally block; Java permits it. Never return from finally.

Java's byte is signed, range −128 to 127. C#'s byte is unsigned and sbyte is the signed one. Reading binary data written by C# code and printing a byte will show negative numbers. Mask with b & 0xFF to get the unsigned value.

Three traps, all of which produce wrong money:

• new BigDecimal(0.1) is wrong. The double literal is already imprecise, so you get 0.1000000000000000055511151231257827. Always use the String constructor, or BigDecimal.valueOf(double) which routes through Double.toString.
• divide without a scale throws ArithmeticException on a non-terminating result such as 1/3. Always supply a scale and a RoundingMode.
• equals compares scale. new BigDecimal("1.0").equals(new BigDecimal("1.00")) is false. Use compareTo.

Duration and Period are not interchangeable. Duration is exact machine time, seconds and nanos. Period is calendar time: years, months, days. Adding one month is a Period operation and lands on a different day-of-month depending on the source date; adding 30 days is a Duration-style operation. Daylight-saving transitions make the distinction load-bearing.

Always pass the cause when wrapping. throw new RuntimeException(e), not throw new RuntimeException(e.getMessage()). Dropping the cause discards the original stack trace, and the resulting production incident is unfixable from logs alone. This is the same as C#'s throw new X("...", inner).

The functional interfaces in java.util.function declare no checked exceptions, so no lambda passed to map, forEach or Optional.map may throw one. This is the single most-complained-about interaction in modern Java.

// does not compile
paths.stream().map(Files::readString).toList();

// the ceremony you actually write
paths.stream()
     .map(p -> {
         try { return Files.readString(p); }
         catch (IOException e) { throw new UncheckedIOException(e); }
     })
     .toList();

Teams commonly extract a small Unchecked.wrap(...) helper, or use a library such as Vavr. There is no language-level fix in Java 25.

If the body throws and close() throws, Java keeps the body's exception as primary and attaches the close failure as a suppressed exception, retrievable via getSuppressed(). C# loses the original in the same situation. Worth knowing when a stack trace shows a "Suppressed:" section.

Tests live under src/test/java but in the same package as the code they test. That is how they get package-private access. Java's replacement for InternalsVisibleTo. A test in a different package cannot see package-private members.

spring-boot-starter-web became spring-boot-starter-webmvc in Boot 4.0, as part of a wider renaming to the pattern spring-boot-<technology>. It is the first line of your first pom.xml, so it is also the first thing that breaks when following a Boot 3 tutorial against Boot 4. See Migrating Boot 3 to 4.