Fix Invalid class name error in Linux – Java

When does this error hit?

You're running a Java app on Linux – maybe a Spring Boot service, a Gradle-built tool, or an old Tomcat webapp. You type java -jar myapp.jar or ./gradlew run and BAM – java.lang.NoClassDefFoundError: Invalid class name. The JVM crashes before the app even starts. Had a client last month whose entire Jenkins pipeline blew up because of this – wasted three hours chasing ghosts.

This error is specific: it's not a missing dependency or a typo in code. The class name is literally rejected as invalid by the JVM's internal loader. It's rare but brutal when it hits.

Why does this happen?

The root cause is almost always one of two things:

Corrupted class file. The .class file on disk is broken – maybe from a bad Maven build, a failed copy over scp, or a disk write error. The JVM can't parse the class name from the bytecode header.
Classpath contains a directory or jar with a name that Java sees as invalid. Java expects class names to follow strict rules: start with a letter, no spaces, no special characters like % or ! in the file path. If your jar is in /home/user/some%20folder/app.jar, the JVM chokes.

I've seen both. The %20 case happened when someone unzipped an archive with spaces in the folder name. The corrupted class case came from a flaky hard drive in a cloud VM that silently bit-flipped a byte in a .class file.

How to fix it – step by step

Step 1: Check the error message for the offending class

Look at the full stack trace. It usually says something like Invalid class name: com/example/MyClass – note the slash, not a dot. That's the internal JVM path. If it shows a weird character (like %20 or a space), that's your culprit.

Step 2: Verify the class file exists and is clean

Run this to find the class file:

find /path/to/your/app -name "*.class" | grep -i "MyClass"

Use javap to check the file is valid:

javap -p /path/to/MyClass.class

If javap says something like "error reading class file" or throws an IOException, the file is corrupt. Rebuild the project. Clean compile:

mvn clean compile   # for Maven
gradle clean build  # for Gradle

Don't skip the clean step. It wipes out any corrupted .class files from the old build.

Step 3: Check the classpath for invalid characters or spaces

If the error doesn't point to a specific class, the problem is in the classpath. Run your app with verbose class loading to see what's being passed:

java -verbose:class -jar myapp.jar 2>&1 | head -50

Look for any path that has spaces, %, !, @, or other special characters. The fix: move the jar or class directory to a path with only letters, numbers, underscores, and dashes. Example:

mv /home/user/some%20folder/app.jar /home/user/apps/jar/app.jar

Then update your run script or environment variable.

Step 4: Check Java version compatibility

I've seen this happen when a class compiled with Java 17 is run on Java 11. The class file format changed – older JVM can't parse the class name header. Check versions:

java -version
javap -verbose MyClass.class | grep "major version"

Major version 61 = Java 17, 55 = Java 11, 52 = Java 8. If they don't match, recompile with the correct target:

mvn -Djava.version=11 clean compile

Step 5: Check for class name typos in code or config

If the class name in your source code or a config file (like Spring XML, Hibernate mappings, or a properties file) has a typo, the JVM will report it as invalid. For example, MyClass vs myclass – Java is case-sensitive. Grep your project for the broken class name:

grep -rn "MyClass" /path/to/source

If you find a mismatch, fix it and rebuild.

Still failing? Check these next

If the error persists after all that, you've got a deeper problem:

Check disk health. Run smartctl -a /dev/sda on the drive where the app lives. Bad sectors can silently corrupt class files during write.
Check for file system issues. sudo dmesg | grep -i error – look for I/O errors. If found, copy the app to another disk and test.
Check your build tool cache. Maven's local repo (~/.m2/repository) can have corrupted jars. Delete the cache for your project: rm -rf ~/.m2/repository/com/yourcompany and rebuild.
Check for antivirus or security software. Some Linux antivirus tools (like ClamAV) can quarantine or corrupt class files if they misidentify them. Exclude your app directory from scanning.

Remember: this error is almost never a code bug. It's an environment or build issue. Start with the class file, then the path, then the version. You'll have it fixed in ten minutes, not three hours like my client.