NullPointerException en Java: causas y cómo solucionarlo

El error más común de Java

Un NullPointerException (todo el mundo lo llama NPE) ocurre cuando intentas usar una referencia que no apunta a nada -null- como si apuntara a un objeto real. Las variables de Java de tipo objeto contienen un objeto o contienen null, el valor que significa "aquí no hay objeto". En el momento en que le pides a null que haga algo -llamar a un método, leer uno de sus campos, indexar dentro de él- no hay nada sobre lo que actuar, así que la JVM lanza la excepción.

A diferencia de try-catch, que usas en la página anterior para gestionar fallos esperados, un NPE casi siempre es un simple error de programación. El objetivo de esta página no es capturarlos, sino entender por qué ocurren y escribir código que no los produzca.

public class Main {
    public static void main(String[] args) {
        String name = null;
        System.out.println(name.length());  // ¡pum!: name es null
    }
}

No hay ningún String sobre el que ejecutar length(), así que el programa se detiene con un NullPointerException.

Leer el mensaje

Desde Java 14, el mensaje te dice exactamente qué era null; a esto se le llama Helpful NullPointerException (NPE útil). Léelo antes de cambiar nada:

Exception in thread "main" java.lang.NullPointerException: Cannot invoke "String.length()" because "name" is null
	at Main.main(Main.java:4)

Importan dos piezas. Cannot invoke "String.length()" es la operación que falló, y because "name" is null nombra al culpable. La línea at Main.main(Main.java:4) es la traza de pila que apunta a la línea exacta. Así que la solución no es "envolver la línea 4 en un try", sino "averiguar por qué name es null en la línea 4". Casi siempre el error está en algún punto anterior, donde el valor debería haberse asignado y no se hizo.

Las formas de provocarlo

Los NPE provienen de un puñado de operaciones, todas variaciones de "tocar null":

import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        // 1. Llamar a un método sobre null
        String s = null;
        // System.out.println(s.toUpperCase());  // NPE

        // 2. Una búsqueda en el mapa que no encuentra nada devuelve null
        Map<String, Integer> ages = new HashMap<>();
        Integer age = ages.get("Ada");   // no existe la clave -> null
        System.out.println("Lookup returned: " + age);

        // 3. Desempaquetar un wrapper null en un primitivo
        // int n = age;   // NPE: no se puede desempaquetar un Integer null a int

        System.out.println("Reached the end safely");
    }
}

Las búsquedas en mapas son una fuente clásica: get devuelve null cuando la clave no existe, y el NPE suele aparecer varias líneas después, cuando por fin usas ese valor. El desempaquetado es el caso traicionero: asignar un Integer que es null a un int lanza la excepción, porque no hay ningún número que copiar.

Protegerse con una comprobación de null

La defensa más simple es un if que confirme que una referencia no es nula antes de usarla:

public class Main {
    public static void main(String[] args) {
        String name = lookupName(7);

        if (name != null) {
            System.out.println(name.toUpperCase());
        } else {
            System.out.println("No name found");
        }
    }

    static String lookupName(int id) {
        return null;  // simulamos que la búsqueda no encontró nada
    }
}

Cuando comparas una variable con un String constante, pon la constante primero: "yes".equals(answer) en lugar de answer.equals("yes"). Si answer es null, la primera forma devuelve false tranquilamente, mientras que la segunda lanza la excepción.

public class Main {
    public static void main(String[] args) {
        String answer = null;

        // Seguro incluso cuando answer es null:
        System.out.println("yes".equals(answer));   // false, sin NPE

        // answer.equals("yes") aquí lanzaría un NullPointerException
    }
}

Fallar rápido con Objects.requireNonNull

Esparcir comprobaciones de null por todas partes resulta ruidoso. Cuando un valor nunca debería ser null -como un argumento de un constructor- valídalo en el límite con Objects.requireNonNull. Lanza la excepción de inmediato, con un mensaje claro, en el punto donde llega el valor incorrecto en lugar de hacerlo más tarde en lo profundo de tu código:

import java.util.Objects;

public class Main {
    public static void main(String[] args) {
        try {
            new Account(null);
        } catch (NullPointerException e) {
            System.out.println("Rejected: " + e.getMessage());
        }
    }

    static class Account {
        final String owner;

        Account(String owner) {
            this.owner = Objects.requireNonNull(owner, "owner must not be null");
        }
    }
}

Este hábito de "fallar rápido" convierte un NPE vago a 200 líneas de distancia en una queja precisa en el origen. Aquí capturar la excepción solo sirve para mostrar el mensaje; en código real la dejarías aflorar para que el error se corrija.

Evitar los null desde el principio

El mejor NPE es el que nunca puede ocurrir porque no hay ningún null que alcanzar. Unos pocos hábitos sirven de mucho:

• Devuelve una colección o cadena vacía, nunca null. Collections.emptyList() y "" son seguros para recorrer y para llamar a sus métodos.
• Usa getOrDefault en los mapas para que una búsqueda fallida produzca un valor real en lugar de null.
• Inicializa los campos al declararlos en lugar de dejarlos en null hasta "más tarde".

import java.util.HashMap;
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        Map<String, Integer> ages = new HashMap<>();
        ages.put("Ada", 36);

        // Sin null, sin riesgo de problemas de desempaquetado:
        int boris = ages.getOrDefault("Boris", 0);
        System.out.println("Boris: " + boris);
    }
}

Cuando un valor es genuinamente opcional -una búsqueda que legítimamente puede no encontrar nada- Java ofrece Optional, un contenedor que obliga a quien lo usa a gestionar el caso "ausente" en lugar de devolver silenciosamente un null. Ese es el concepto relacionado que leer a continuación si quieres eliminar por completo estos huecos del diseño de tus API.

Para terminar

Un NullPointerException es Java diciéndote que usaste una referencia que contenía null como si contuviera un objeto. La solución rara vez es capturarlo: es leer el mensaje útil, rastrear hasta dónde debería haberse asignado el valor y, o bien garantizar que no sea nulo, o bien proteger el punto donde lo usas. Apóyate en Objects.requireNonNull para fallar rápido en los límites, prefiere valores vacíos y getOrDefault antes que null, y recurre a Optional cuando la ausencia sea un resultado real y esperado. Domina esa mentalidad y el error más común de Java se convertirá en uno de los más raros en tu propio código.