1.1.18 Diagnosing a NullReferenceException

A NullReferenceException Means Code Tried to Use an Object Through null

An object reference can either refer to an object or have the value:

Activity diagram showing player1, then team, then name.
Player.
  • New
  • Changed
  • Removed

To reach name, the program first needs:

  1. player1 to refer to a Player object;
  2. player1.team to refer to a Team object.

If player1.team is null, the program cannot continue to ..name.

Find the First null Reference in the Chain

Imagine the debugger shows:

Object diagram showing player1 Player object, then player1.team null.
Player1PlayerObject.
  • New
  • Changed
  • Removed

Now the failure is more precise.

The problem is not that player1 is null.

player1 exists.

The nested reference:

player1.team

does not currently point to a Team object.

That is the reference you need to explain.

Connect the Runtime State to the Object Model

Suppose the UML object diagram says:

player1 : Player  --------  team1 : Team

The model expects a relationship between those two objects.

If the C# runtime state shows:

player1.team = null

then the runtime object does not yet represent the modeled relationship.

That gives you an evidence-based diagnosis:

Use the Autos Window to Inspect the Reference

Pause at or immediately before the failing statement.

In Autos, inspect:

player1

Expand the object.

Find the relevant nested field.

For example:

player1
  name = "Jordan"
  team = null

The debugger shows the state that caused the member-access chain to fail.

Do Not Assume Which Reference Is Null

Consider:

player1.team.coach.name

Possible null references include:

  • player1 ;
  • player1.team ;
  • player1.team.coach .

The exception type alone does not tell you which one.

Inspect the chain step by step.

That habit becomes increasingly important as object relationships become deeper.

Diagnose Before Editing

A strong process is:

  1. Identify the failing statement.
  2. Break the member-access chain into steps.
  3. Inspect each reference in order.
  4. Find the first reference whose value is null .
  5. Compare that state with the UML or requirement.
  6. Determine which earlier relationship assignment should have established the reference.

This is better than adding random object creation statements.

Do Not Automatically Create a New Object at the Failure Point

Suppose:

player1.team = null

The quick reaction might be:

player1.team = new Team();

That creates a Team object.

It may be the wrong Team object.

If the UML already contains:

team1 : Team

the intended correction may be to connect player1 to that existing team1.

The model controls which object relationship is required.

Null Can Be a Valid Temporary State

A reference field can begin as null by default.

The presence of null is not automatically a defect.

It becomes a problem when the program attempts an operation that assumes an object exists there.

Ask:

The requirement and sequence answer that question.

The Main Diagnostic Sentence

When you encounter a NullReferenceException, work toward a sentence such as:

That sentence identifies:

  • the object that exists;
  • the reference that is null;
  • the member access that fails.

A precise diagnosis makes the correction much easier to reason about.