La compilación falla: undefined reference — cómo encontrar y corregir el error

«Undefined reference» — el principal enemigo del principiante en C++ (y no solo)

Escribes código, todo se ve perfecto, el compilador calla, presionas «Compilar» — y entonces… un muro de texto rojo. El protagonista de esta pesadilla es undefined reference (o unresolved external symbol). ¿Te suena? Si alguna vez has programado en C++, seguro que te has encontrado con este error. Asusta a los principiantes, pero en realidad es solo una señal: «Sé de qué función hablas, pero no puedo encontrar su implementación».

En este tutorial, analizaremos qué es el error de referencia no definida, por qué ocurre y, lo más importante, cómo solucionarlo. Conocerás las 5 causas más comunes y obtendrás una lista de verificación lista para usar para resolver el problema. ¡Allá vamos!

¿Qué es undefined reference / unresolved external symbol?

Empecemos con la teoría, pero solo un poco. El proceso de compilación de un programa en C++ consta de dos etapas:

\n
• Compilación — cada archivo .cpp se convierte en un archivo objeto (.o o .obj). El compilador verifica la sintaxis y recuerda qué funciones están declaradas (prototipos).
\n
• Enlace (linkeo) — el enlazador (linker) une todos los archivos objeto y bibliotecas en un único archivo ejecutable. En esta etapa, busca las implementaciones de todas las funciones prometidas.
\n

El error undefined reference (en Visual Studio — unresolved external symbol) ocurre precisamente en la etapa de enlace. El compilador pasó exitosamente, pero el enlazador no encontró el cuerpo de la función. Grita: «¡Dijiste que la función foo() existe, pero no puedo encontrar dónde está definida!».

Top 5 causas del error undefined reference en C++

Analicemos los escenarios más comunes con ejemplos reales. En cada caso, mostraré el código erróneo y la forma de solucionarlo.

1. Declaraste pero no definiste la función

Un clásico. Escribiste el prototipo de la función pero olvidaste la implementación.

// main.cpp\n#include <iostream>\n\nvoid hello(); // declaración (prototipo)\n\nint main() {\n    hello();\n    return 0;\n}\n// ¡Falta la implementación de hello()!\n

Error de enlace: undefined reference to `hello()'. Solución: escribe el cuerpo de la función.

2. No incluiste el archivo con la implementación en la compilación

Este es un problema común al trabajar con varios archivos .cpp. Supongamos que declaraste la función en utils.h, la definiste en utils.cpp, pero olvidaste agregar utils.cpp al comando de compilación.

// utils.h\nvoid printMessage();\n\n// utils.cpp\n#include <iostream>\n#include "utils.h"\nvoid printMessage() {\n    std::cout << "¡Hola!" << std::endl;\n}\n\n// main.cpp\n#include "utils.h"\nint main() {\n    printMessage();\n    return 0;\n}\n

Si compilas solo main.cpp (g++ main.cpp), el enlazador no verá utils.cpp. Solución: compila ambos archivos juntos: g++ main.cpp utils.cpp -o program.

3. La clase o plantilla está definida en .cpp, no en .h

Este es un dolor específico de C++. Si defines un método de clase directamente en el archivo .cpp, pero solo incluyes el encabezado, el enlazador no encontrará la implementación.

// MyClass.h\nclass MyClass {\npublic:\n    void doSomething();\n};\n\n// MyClass.cpp\n#include "MyClass.h"\nvoid MyClass::doSomething() { /* ... */ }\n\n// main.cpp\n#include "MyClass.h"\nint main() {\n    MyClass obj;\n    obj.doSomething(); // Error: undefined reference\n    return 0;\n}\n

Solución: asegúrate de que MyClass.cpp participe en la compilación (ver punto 2).

4. Enlace incorrecto de bibliotecas (por ejemplo, math.h)

Algunas bibliotecas (como la matemática libm) requieren una indicación explícita