Blog

A Java compiler message such as cannot find symbol usually points to the line where the compiler noticed the problem, not always the line that caused it. A misspelled variable, a method called by the wrong name, or a missing import can all trigger it. Read the symbol named in the error, then check its spelling, declaration, scope, and capitalization.

Good debugging reduces uncertainty. Rather than changing several lines and running the program again, identify the type of failure, reproduce it, inspect the relevant state, and make one justified change. It may take an extra minute at the start, but it saves hours of guessing later.

Classify the failure before changing code

Java problems usually fall into three categories: compile-time errors, runtime exceptions, and incorrect behavior with no error message. Each calls for a different approach.

Failure type	When it appears	Useful first action
Compile-time error	Before the program starts	Read the compiler message and inspect the named file and line
Runtime exception	While code is running	Read the exception type and stack trace from top to bottom
Logic error	Program runs but gives a wrong result	Check inputs, assumptions, intermediate values, and expected output

Do not hide failures with empty catch blocks or broad exception handling that prints only a vague message. That removes the evidence you need to find the defect. Catch an exception only when the application can recover meaningfully, report a clear failure, or release a resource safely.

Compile-time errors: syntax, names, and types

Missing punctuation and unmatched delimiters

A missing semicolon, closing parenthesis, brace, or quotation mark can produce a long list of messages below the real mistake. For example, a missing } may cause class, interface, enum, or record expected to appear near the end of the file.

Use your IDE's automatic formatting. Consistent indentation makes unmatched braces easier to spot. Most Java IDEs also highlight paired delimiters, so place the cursor beside a brace or parenthesis and confirm that its matching partner is where it should be.

if (score >= 50) {
    System.out.println("Passed");
// missing closing brace

Fixing the missing brace matters more than addressing every compiler message that follows it.

Names are case-sensitive

userName, username, and UserName are three different identifiers. Java convention uses camelCase for variables and methods and PascalCase for classes. These conventions make capitalization mistakes easier to notice.

String userName = "Amina";
System.out.println(username); // error: cannot find symbol

When Java cannot find a symbol, make sure it exists in the current scope. A local variable declared inside an if block or loop is unavailable after that block ends.

if (loggedIn) {
    String greeting = "Welcome";
}
System.out.println(greeting); // greeting is out of scope

Type mismatches and unintended integer division

Java's type system catches incompatible assignments before the program runs. A common beginner mistake is assigning text to a numeric variable or treating a number as text without converting it.

int age = "18"; // incompatible types

Convert values only when the conversion is valid and intentional:

int age = Integer.parseInt("18");

Parsing user-supplied text can throw NumberFormatException, so the input may need validation or exception handling. Do not assume every value is well-formed.

Integer division is a logic problem that can look like a type issue. Because both operands below are integers, Java drops the fractional part:

int completed = 1;
int total = 2;
double progress = completed / total; // 0.0, not 0.5

Make at least one operand floating-point before dividing:

double progress = (double) completed / total; // 0.5

Imports, packages, and project structure

An import error can mean that a class has not been imported, a dependency is missing, or a package declaration does not match the folder layout. For standard library classes, add the relevant import, such as import java.util.Scanner;. For classes in your own project, check the package declaration and source root before accepting random imports suggested by the IDE.

If the IDE says a package does not exist while the command-line build succeeds, refresh the project configuration and verify the selected Java Development Kit (JDK). When using a build tool, reload its dependency configuration instead of copying library files into arbitrary folders.

Runtime exceptions: use the stack trace as evidence

A stack trace shows the exception type, its message, and the chain of method calls that led to it. The first line states what failed. Then find the first stack-frame line that refers to your own code; that is usually the best place to start. Framework and library frames can provide context, but begin with your file and line number.

NullPointerException

A NullPointerException happens when code uses a reference whose value is null. Common cases include calling a method, reading a field, indexing through a null array reference, or receiving an absent value from another method.

String city = null;
System.out.println(city.length());

The answer is not to put a null check around every dereference. Find out why city is null. An object may never have been initialized, a lookup may have found no result, or a method contract may allow an absent return value. Then choose a deliberate policy: reject missing data, provide a default, return an Optional where appropriate, or initialize the object before using it.

For comparisons, putting a known non-null literal first avoids one common failure:

if ("admin".equals(role)) {
    // safe even if role is null
}

ArrayIndexOutOfBoundsException and StringIndexOutOfBoundsException

Arrays and strings use zero-based indexes. An array with length 5 has valid indexes from 0 through 4. In a forward loop, the condition normally needs <, not <=.

int[] values = {4, 8, 15};
for (int i = 0; i <= values.length; i++) {
    System.out.println(values[i]);
}

The final iteration tries to access index 3, which does not exist. Use:

for (int i = 0; i < values.length; i++) {
    System.out.println(values[i]);
}

When an index is calculated instead of controlled by a simple loop, inspect or print both the index and the collection length just before the failing access. This helps show whether the problem is in the input, boundary condition, or calculation.

NumberFormatException and input problems

Integer.parseInt() accepts a specific integer format. Blank text, decimal values, misplaced spaces, and non-numeric characters can all fail. Normalize input deliberately and report validation problems clearly.

String rawAge = input.trim();
if (!rawAge.matches("\d+")) {
    throw new IllegalArgumentException("Age must contain whole digits");
}
int age = Integer.parseInt(rawAge);

In larger applications, a regular expression should not be the only validation rule when domain requirements are more involved. Parsing tells you whether the text is numeric. Business rules determine whether the resulting number is acceptable, such as whether it falls within an allowed range.

Logic errors: when Java does exactly what you told it to do

Logic errors are often easiest to find with a small, known test case. If a method calculates a discount, test zero, one ordinary value, a boundary value, and a value just beyond that boundary. Write down the expected result before running the code. That makes it easier to tell a code defect from a mistaken expectation.

Comparing objects with == instead of equals

The == operator compares primitive values directly. For objects, it usually checks whether two references point to the same object. Compare string content with equals().

String first = new String("Java");
String second = new String("Java");

System.out.println(first == second);        // usually false
System.out.println(first.equals(second));   // true

== can appear to work with certain string literals because of string pooling. That is an implementation detail, not a valid way to compare string contents.

Assignment inside a condition

A condition can accidentally assign a boolean value instead of comparing one:

boolean enabled = false;
if (enabled = true) {
    System.out.println("Feature enabled");
}

This compiles and always enters the branch because the assignment expression evaluates to true. Prefer direct boolean checks such as if (enabled), and turn on IDE inspections that flag suspicious assignments in conditions.

Mutable state leaking between tests or method calls

Fields, static collections, and reused objects can keep data longer than expected. A test may pass on its own but fail after another test because a shared list was not cleared. Keep method state local where possible, pass dependencies explicitly, and create fresh test data for each test.

A repeatable debugging workflow

1. Reproduce the issue. Record the exact input, command, and environment that trigger it. Intermittent failures are easier to diagnose when their conditions are written down.
2. Preserve the original evidence. Copy the full compiler output or stack trace before making changes.
3. Reduce the case. Remove unrelated code or create a small test that demonstrates the problem. A minimal reproducible example often reveals a mistaken assumption.
4. Inspect state at the boundary. Check method arguments, return values, indexes, and object fields where data first becomes invalid.
5. Use a breakpoint when output is not enough. Pause before the failing line, step into a suspicious method, and inspect variables one statement at a time.
6. Fix the cause and rerun the same case. Then add a test that would fail if the defect returned.

Temporary logging can help, but do not print passwords, API tokens, session identifiers, personal data, or full production records. Safer diagnostics include a request identifier, record count, value type, or a redacted value. This follows the same protective habits discussed in Digital Hygiene for Developers: Protect Accounts, Secrets, and Projects.

Make the IDE work for you

A debugger works best when you have a specific failure path. Set a breakpoint on the line before an exception or incorrect result, run the program in debug mode, reproduce the problem, and inspect local variables and the call stack. Step over a line when you trust the method call; step into it when you suspect its internal behavior.

Conditional breakpoints are useful in large loops. You might pause only when i == 999 or when an object's ID matches the failing test record. Use them carefully: complex conditions can slow debugging and may cause side effects if they call methods that change state.

Static analysis and compiler warnings catch many problems early, including unused variables, accidental null dereferences, resource leaks, and unchecked conversions. Treat warnings as prompts to investigate rather than clutter. A resource warning may show that a file, stream, or database connection is not closed on every execution path.

When the bug is outside the line that fails

A failure in one method may come from invalid data created much earlier. Work backward through the call stack and find the first point where the value no longer matches its expected form. Add a narrow assertion or validation check there. If a method requires a non-empty account ID, for example, detect that at the public method boundary rather than allowing a null-related failure later in database or formatting code.

Assertions are useful for internal assumptions that should never be false during development:

assert index >= 0 && index < values.length : "index must be in range";

Do not rely on assertions to validate untrusted or user-controlled input, because assertions can be disabled at runtime. Use normal validation and clear exceptions for external data. Finally, add a focused unit test using the exact input that caused the failure, verify the expected result, and keep that test in the project as a regression guard.