NullReferenceException Class

 

The exception that is thrown when there is an attempt to dereference a null object reference.

Namespace:   System
Assembly:  mscorlib (in mscorlib.dll)

System.Object
  System.Exception
    System.SystemException
      System.NullReferenceException

[<SerializableAttribute>]
[<ComVisibleAttribute(true)>]
type NullReferenceException = 
    class
        inherit SystemException
    end

NameDescription
System_CAPS_pubmethodNullReferenceException()

Initializes a new instance of the NullReferenceException class, setting the Message property of the new instance to a system-supplied message that describes the error, such as "The value 'null' was found where an instance of an object was required." This message takes into account the current system culture.

System_CAPS_protmethodNullReferenceException(SerializationInfo, StreamingContext)

Initializes a new instance of the NullReferenceException class with serialized data.

System_CAPS_pubmethodNullReferenceException(String)

Initializes a new instance of the NullReferenceException class with a specified error message.

System_CAPS_pubmethodNullReferenceException(String, Exception)

Initializes a new instance of the NullReferenceException class with a specified error message and a reference to the inner exception that is the cause of this exception.

NameDescription
System_CAPS_pubpropertyData

Gets a collection of key/value pairs that provide additional user-defined information about the exception.(Inherited from Exception.)

System_CAPS_pubpropertyHelpLink

Gets or sets a link to the help file associated with this exception.(Inherited from Exception.)

System_CAPS_pubpropertyHResult

Gets or sets HRESULT, a coded numerical value that is assigned to a specific exception.(Inherited from Exception.)

System_CAPS_pubpropertyInnerException

Gets the Exception instance that caused the current exception.(Inherited from Exception.)

System_CAPS_pubpropertyMessage

Gets a message that describes the current exception.(Inherited from Exception.)

System_CAPS_pubpropertySource

Gets or sets the name of the application or the object that causes the error.(Inherited from Exception.)

System_CAPS_pubpropertyStackTrace

Gets a string representation of the immediate frames on the call stack.(Inherited from Exception.)

System_CAPS_pubpropertyTargetSite

Gets the method that throws the current exception.(Inherited from Exception.)

NameDescription
System_CAPS_pubmethodEquals(Object)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetBaseException()

When overridden in a derived class, returns the Exception that is the root cause of one or more subsequent exceptions.(Inherited from Exception.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetObjectData(SerializationInfo, StreamingContext)

When overridden in a derived class, sets the SerializationInfo with information about the exception.(Inherited from Exception.)

System_CAPS_pubmethodGetType()

Gets the runtime type of the current instance.(Inherited from Exception.)

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Creates and returns a string representation of the current exception.(Inherited from Exception.)

NameDescription
System_CAPS_proteventSerializeObjectState

Occurs when an exception is serialized to create an exception state object that contains serialized data about the exception.(Inherited from Exception.)

A NullReferenceException exception is thrown when you try to access a member on a type whose value is null. A NullReferenceException exception typically reflects developer error and is thrown in the following scenarios:

  • You've forgotten to instantiate a reference type. In the following example, names is declared but never instantiated:

    No code example is currently available or this language may not be supported.

    Some compilers issue a warning when they compile this code. Others issue an error, and the compilation fails. To address this problem, instantiate the object so that its value is no longer null. The following example does this by calling a type's class constructor.

    No code example is currently available or this language may not be supported.
  • You've forgotten to dimension an array before initializing it. In the following example, values is declared to be an integer array, but the number of elements that it contains is never specified. The attempt to initialize its values therefore thrown a NullReferenceException exception.

    No code example is currently available or this language may not be supported.

    You can eliminate the exception by declaring the number of elements in the array before initializing it, as the following example does.

    No code example is currently available or this language may not be supported.

    For more information on declaring and initializing arrays, see Arrays (C# Programming Guide) and Arrays in Visual Basic.

  • You get a null return value from a method, and then call a method on the returned type. This sometimes is the result of a documentation error; the documentation fails to note that a method call can return null. In other cases, your code erroneously assumes that the method will always return a non-null value.

    The code in the following example assumes that the Array.Find<'T> method always returns Person object whose FirstName field matches a search string. Because there is no match, the runtime throws a NullReferenceException exception.

    No code example is currently available or this language may not be supported.

    To address this problem, test the method's return value to ensure that it is not null before calling any of its members, as the following example does.

    No code example is currently available or this language may not be supported.
  • You're using an expression (for example, you're chaining a list of methods or properties together) to retrieve a value and, although you're checking whether the value is null, the runtime still throws a NullReferenceException exception. This occurs because one of the intermediate values in the expression returns null. As a result, your rest for null is never evaluated.

    The following example defines a Pages object that caches information about web pages, which are presented by Page objects. The Example.Main method checks whether the current web page has a non-null title and, if it does, displays the title. Despite this check, however, the method throws a NullReferenceException exception.

    No code example is currently available or this language may not be supported.

    The exception is thrown because pages.CurrentPage returns null if no page information is stored in the cache. This exception can be corrected by testing the value of the CurrentPage property before retrieving the current Page object's Title property, as the following example does:

    No code example is currently available or this language may not be supported.
  • You're enumerating the elements of an array that contains reference types, and your attempt to process one of the elements throws a NullReferenceException exception.

    The following example defines a string array. A for statement enumerates the elements in the array and calls each string's Trim method before displaying the string.

    No code example is currently available or this language may not be supported.

    This exception occurs if you assume that each element of the array must contain a non-null value, and the value of the array element is in fact null. The exception can be eliminated by testing whether the element is null before performing any operation on that element, as the following example shows.

    No code example is currently available or this language may not be supported.
  • A NullReferenceException exception is thrown by a method that is passed null. Some methods validate the arguments that are passed to them. If they do and one of the arguments is null, the method throws an System.ArgumentNullException exception. Otherwise, it throws a NullReferenceException exception. The following example illustrates this scenario.

    No code example is currently available or this language may not be supported.

    To address this issue, make sure that the argument passed to the method is not null, or handle the thrown exception in a try…catch…finally block. For more information, see Handling and Throwing Exceptions.

The following Microsoft intermediate language (MSIL) instructions throw NullReferenceException: callvirt, cpblk, cpobj, initblk, ldelem.<type>, ldelema, ldfld, ldflda, ldind.<type>, ldlen, stelem.<type>, stfld, stind.<type>, throw, and unbox.

NullReferenceException uses the HRESULT COR_E_NULLREFERENCE, which has the value 0x80004003.

For a list of initial property values for an instance of NullReferenceException, see the NullReferenceException constructors.

Handling NullReferenceException in release code

It's usually better to avoid a NullReferenceException than to handle it after it occurs. Handling an exception can make your code harder to maintain and understand, and can sometimes introduce other bugs. A NullReferenceException is often a non-recoverable error. In these cases, letting the exception stop the app might be the best alternative.

However, there are many situations where handling the error can be useful:

  • Your app can ignore objects that are null. For example, if your app retrieves and processes records in a database, you might be able to ignore some number of bad records that result in null objects. Recording the bad data in a log file or in the application UI might be all you have to do.

  • You can recover from the exception. For example, a call to a web service that returns a reference type might return null if the connection is lost or the connection times out. You can attempt to reestablish the connection and try the call again.

  • You can restore the state of your app to a valid state. For example, you might be performing a multi-step task that requires you to save information to a data store before you call a method that throws a NullReferenceException. If the uninitialized object would corrupt the data record, you can remove the previous data before you close the app.

  • You want to report the exception. For example, if the error was caused by a mistake from the user of your app, you can generate a message to help him supply the correct information. You can also log information about the error to help you fix the problem. Some frameworks, like ASP.NET, have a high-level exception handler that captures all errors to that the app never crashes; in that case, logging the exception might be the only way you can know that it occurs.

Universal Windows Platform
Available since 8
.NET Framework
Available since 1.1
Portable Class Library
Supported in: portable .NET platforms
Silverlight
Available since 2.0
Windows Phone Silverlight
Available since 7.0
Windows Phone
Available since 8.1

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: