🎮 UnityDocs

NullReferenceException: object reference not set

El error más común de Unity explicado a fondo: por qué ocurre, cómo leer el mensaje para localizarlo, cómo solucionarlo y, sobre todo, cómo prevenirlo.

🐛 ErrorPrincipiante✅ RevisadoUnity 6.0 LTSActualizado 2026-07-14
DificultadConceptual Código Matemáticas
Tiempo📖 Lectura 6 min

El mensaje#

texto
NullReferenceException: Object reference not set to an instance of an object
  Jugador.Update () (at Assets/Scripts/Jugador.cs:23)

Qué significa#

Estás intentando usar (leer una propiedad, llamar a un método) una variable que no apunta a nada (null). Es como intentar abrir una puerta que no existe.

Lo más importante: la última línea

La pista está en la ruta final: Jugador.cs:23. Ve a ese archivo y esa línea. Ahí hay una variable que vale null en el momento de ejecutarse. El 90% del trabajo es localizar cuál de las variables de esa línea es la nula.

Por qué ocurre (causas típicas)#

  • Referencia sin asignar en el Inspector: declaraste [SerializeField] private Transform objetivo; pero olvidaste arrastrar el objeto en el Inspector, así que vale null.
  • GetComponent que no encuentra nada: GetComponent<Rigidbody>() devuelve null si el objeto no tiene ese componente.
  • Find que no encuentra el objeto: un nombre mal escrito o un objeto desactivado.
  • Usar algo en Awake que se crea en Start de otro script (problema de orden).
  • Objeto ya destruido: guardaste una referencia y luego hiciste Destroy; ahora está "muerta".

Cómo detectarlo#

C#
void Update()
{
    // Si 'objetivo' es null, esta línea lanza NullReferenceException
    transform.position = objetivo.position;
}

Añade un log temporal para confirmar cuál es null:

C#
if (objetivo == null)
    Debug.LogError("objetivo no está asignado en " + name, this);

Pasar this como segundo argumento hace que, al clicar el error en la consola, Unity resalte el objeto culpable en la Hierarchy.

Cómo solucionarlo#

  • Si es una referencia del Inspector: arrástrala. Comprueba que no quedó vacía tras duplicar el prefab.
  • Si es un GetComponent: asegúrate de que el componente existe, o usa TryGetComponent.
  • Si es de orden: mueve la lectura de Awake a Start, o revisa Script Execution Order.

Cómo prevenirlo#

C#
// 1) Comprobar antes de usar
if (objetivo != null)
    transform.position = objetivo.position;

// 2) Operador condicional nulo
objetivo?.GetComponent<Renderer>();

// 3) TryGetComponent en vez de GetComponent + comprobación
if (TryGetComponent<Rigidbody>(out var rb))
    rb.AddForce(Vector3.up);

// 4) Forzar que la referencia exista en el editor
[SerializeField] private Transform objetivo;   // y asígnala siempre
El null 'especial' de Unity

Unity sobreescribe el operador == para objetos destruidos: un objeto al que hiciste Destroy se comporta como null al compararlo con == null, aunque técnicamente la referencia de C# siga existiendo. Por eso if (obj == null) es la forma correcta de comprobar objetos de Unity, pero el operador ?. (que usa el null de C#, no el de Unity) puede darte falsos negativos con objetos destruidos. Es un matiz famoso.

Resumen#

NullReferenceException = estás usando algo que vale null. Mira la línea que indica el error, averigua qué variable es nula y por qué (Inspector sin asignar, GetComponent fallido, orden de ejecución u objeto destruido), y protégete con comprobaciones o TryGetComponent.

Fuentes y para profundizar