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:

null

When code tries to access an instance member through a reference that is currently null, C# can throw:

NullReferenceException

The error is not simply:

Something is wrong with the class.

It tells you to investigate a reference used by the failing statement.

Begin With the Statement That Failed

Suppose the source contains:

player1.team.name

This expression has more than one step.

Conceptually:

player1
   ↓
team
   ↓
name

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:

player1 → Player object
player1.team → null

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:

The Player exists, but its Team reference has not been assigned to the Team object required by the model.

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:

At this execution point, was this reference supposed to have been assigned already?

The requirement and sequence answer that question.

The Main Diagnostic Sentence

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

player1 exists, but player1.team is null, so the program cannot access player1.team.name.

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.