SyntaxError aparece cuando Python no puede interpretar la estructura del código. El programa ni siquiera comienza a ejecutarse porque el analizador encuentra una instrucción incompleta, un símbolo fuera de lugar o una construcción que no pertenece a la gramática del lenguaje. Aunque el mensaje puede intimidar al principio, casi siempre se resuelve leyendo la línea indicada y revisando unas pocas líneas anteriores.
Este problema forma parte de los errores comunes de Python. Para investigarlo también resulta útil aprender a depurar en VS Code, entender try y except, organizar el código con funciones y conocer la guía específica para corregir SyntaxError.
Qué significa SyntaxError
Python analiza el archivo antes de ejecutarlo. Durante esa fase comprueba si las palabras clave, operadores, paréntesis, indentación y demás elementos forman instrucciones válidas. Si no puede construir una representación coherente, detiene el proceso y muestra algo parecido a esto:
File "programa.py", line 4
if edad >= 18
^
SyntaxError: expected ':'
La flecha señala el lugar donde el analizador detectó que algo no encajaba. No siempre es el punto exacto donde comenzó el problema. Una comilla o un paréntesis sin cerrar en la línea anterior puede provocar que el error aparezca más adelante.
La documentación oficial sobre errores y excepciones distingue los errores de sintaxis de las excepciones que surgen durante la ejecución. La referencia léxica de Python explica cómo se reconocen cadenas, números, identificadores y delimitadores.
Leer el traceback correctamente
Comienza por el nombre del archivo y el número de línea. Después observa el fragmento mostrado, la flecha y el mensaje final. En versiones modernas de Python, los mensajes suelen indicar qué símbolo falta.
Revisa en este orden:
- La línea marcada.
- La línea inmediatamente anterior.
- El bloque completo donde aparece.
- Los delimitadores abiertos unas líneas antes.
No cambies muchas cosas al mismo tiempo. Corrige una hipótesis, guarda el archivo y vuelve a ejecutar.
Falta de dos puntos
Las estructuras que abren un bloque necesitan dos puntos:
# Incorrecto
if temperatura > 30
print("Hace calor")
# Correcto
if temperatura > 30:
print("Hace calor")
Esto también se aplica a elif, else, for, while, def, class, try, except, finally, with, match y case.
Paréntesis, corchetes o llaves sin cerrar
# Incorrecto
numeros = [1, 2, 3
print(sum(numeros))
# Correcto
numeros = [1, 2, 3]
print(sum(numeros))
Cuando una colección, llamada o expresión ocupa varias líneas, utiliza una forma visual consistente:
usuario = {
"nombre": "Lucía",
"activo": True,
"roles": ["editor", "autor"],
}
Los editores modernos resaltan parejas de delimitadores. Si haces clic junto a uno y no aparece su pareja, probablemente encontraste el problema.
Comillas sin cerrar
# Incorrecto
mensaje = "Hola mundo
# Correcto
mensaje = "Hola mundo"
También puede ocurrir al mezclar comillas dentro de una cadena:
# Correcto
mensaje = 'Ella dijo "hola"'
otro = "Ella dijo \"hola\""
Para texto multilínea utiliza triples comillas, pero asegúrate de cerrarlas con el mismo tipo.
Indentación incorrecta
La indentación tiene significado sintáctico. Usa cuatro espacios por nivel y evita mezclar tabulaciones con espacios:
# Incorrecto
def saludar(nombre):
print(f"Hola, {nombre}")
# Correcto
def saludar(nombre):
print(f"Hola, {nombre}")
Algunos problemas de indentación generan IndentationError o TabError, que son subtipos relacionados. Configura el editor para insertar espacios cuando presionas Tab y mostrar caracteres invisibles si sospechas una mezcla.
Operadores escritos como en otros lenguajes
Python utiliza palabras y símbolos específicos:
# Incorrecto
if activo && administrador:
print("Acceso")
# Correcto
if activo and administrador:
print("Acceso")
No uses || para “o”, ! como negación independiente ni llaves para delimitar bloques. Los operadores correctos son and, or y not.
Asignación dentro de una condición
# Incorrecto
if edad = 18:
print("Exactamente 18")
# Correcto
if edad == 18:
print("Exactamente 18")
= asigna un valor y == compara. El operador := permite expresiones de asignación en situaciones concretas, pero no sustituye indiscriminadamente a ninguno de los anteriores.
Palabras clave mal escritas
# Incorrecto
els:
print("Otro caso")
# Correcto
else:
print("Otro caso")
Otros errores frecuentes son escribir elseif en lugar de elif, function en lugar de def, true en lugar de True o null en lugar de None. El resaltado de sintaxis suele revelar que una palabra no fue reconocida.
Argumentos en orden inválido
En una llamada, los argumentos posicionales deben aparecer antes que los nombrados:
# Incorrecto
crear_usuario(activo=True, "Ana")
# Correcto
crear_usuario("Ana", activo=True)
En una definición, los parámetros sin valor predeterminado deben aparecer antes de los que sí lo tienen:
# Incorrecto
def registrar(nombre="Invitado", edad):
pass
# Correcto
def registrar(edad, nombre="Invitado"):
pass
f-strings mal formadas
nombre = "Ana"
# Incorrecto
print(f"Hola {nombre")
# Correcto
print(f"Hola {nombre}")
Las expresiones dentro de llaves deben estar completas. En Python reciente las f-strings aceptan más construcciones que antes, pero el código debe ejecutarse con una versión compatible.
Versión de Python incompatible
Una sintaxis válida en una versión moderna puede fallar en una antigua. Por ejemplo, match-case requiere Python 3.10 o posterior. Comprueba la versión real del intérprete:
python --version
python -c "import sys; print(sys.executable)"
El editor, el terminal y el servidor deben usar el mismo entorno. Un proyecto puede ejecutarse con un intérprete distinto del que seleccionaste visualmente.
Detectar errores sin ejecutar todo
El módulo py_compile verifica la sintaxis de un archivo:
python -m py_compile programa.py
Para una carpeta completa puedes usar compileall:
python -m compileall src
Estas órdenes son útiles en integración continua porque fallan antes de ejecutar pruebas más lentas.
Usar un formateador y un linter
Herramientas como Ruff, Black o el analizador del editor detectan construcciones problemáticas mientras escribes. Un formateador no arregla todos los errores, pero una estructura visual uniforme hace más evidentes las comillas, sangrías y delimitadores incorrectos.
python -m pip install ruff
ruff check .
Por qué try-except no corrige SyntaxError
Un bloque try funciona después de que el archivo fue analizado. Si el propio archivo contiene sintaxis inválida, Python no puede llegar al bloque. Solo en escenarios avanzados, al compilar texto dinámico con compile o exec, es posible capturar SyntaxError. No uses ejecución dinámica para evitar corregir el código fuente.
Método práctico de corrección
Primero reproduce el error con el comando más pequeño posible. Lee el último mensaje, abre la línea indicada y revisa la anterior. Cuenta delimitadores, comprueba dos puntos y comillas, confirma la indentación y verifica la versión. Si el archivo es grande, comenta temporalmente bloques completos o crea un ejemplo mínimo. Después de corregirlo, ejecuta pruebas para asegurarte de que la intención lógica también es correcta.
Errores frecuentes al investigar
No asumas que la flecha siempre señala la causa inicial. No instales paquetes para solucionar una gramática inválida. No borres líneas al azar ni conviertas todo en una sola instrucción. También evita copiar código con comillas tipográficas, espacios invisibles o guiones especiales desde documentos formateados.
Conclusión
SyntaxError indica que Python no puede comprender la estructura del programa. La solución suele estar en dos puntos, delimitadores, comillas, indentación, operadores, orden de argumentos o compatibilidad de versión. Lee el mensaje completo, revisa primero la línea anterior y usa py_compile o un linter para detectar problemas temprano. Con un proceso sistemático, este error deja de ser una barrera y se convierte en una pista precisa.
