Resuelva el TypeError: se requiere un número entero en Python

El mensaje TypeError: an integer is required aparece cuando el código Python entrega a una función un valor del tipo incorrecto: la función pedía un entero y recibió otra cosa, normalmente una cadena. Suele aparecer en bucles que alimentan chr() con caracteres de una cadena, en ajustes pasados como texto en lugar de números y en innumerables llamadas similares.

Esta guía explica qué significa realmente el mensaje, cómo encontrar el valor que lo provocó y cómo elegir la corrección que coincida con lo que pretendías que hiciera el código.

Qué significa “TypeError: an integer is required”

Un TypeError con esta redacción informa de un único argumento fallido: una función o método declaró que uno de sus parámetros debe ser un entero —un punto de código Unicode, un conteo, una longitud máxima, un modo de archivo— y el valor que recibió no lo era. La comprobación ocurre al analizar la llamada, por lo que la función falla antes de hacer ningún trabajo.

Python expresa este mismo fallo de varias formas según la función que lo lance y la versión que ejecutes. Puedes ver an integer is required, an integer is required (got type str) o 'str' object cannot be interpreted as an integer. Las tres son TypeError y las tres significan lo mismo: el tipo del argumento no cumplió el requisito del parámetro.

No lo confundas con la familia de mensajes unsupported operand type(s). Una expresión como "10" + 5 lanza TypeError: can only concatenate str (not "int") to str, que describe dos operandos que no se pueden combinar: un diagnóstico distinto con una corrección distinta, aunque también sea un TypeError.

Por qué ocurre este error

Las funciones integradas y las partes de la biblioteca estándar implementadas en C analizan sus argumentos de forma estricta. Cuando el analizador encuentra una cadena donde se requiere un entero, la llamada se detiene de inmediato. Un desencadenante mínimo es el parámetro maxlen de collections.deque, que debe ser un entero:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

from collections import deque

try:
    queue = deque([], "3")
except TypeError as error:
    print(f"{type(error).__name__}: {error}")

TypeError: an integer is required

Una forma más común de cometer el mismo error es llamar a chr() dentro de un bucle sobre una cadena. Iterar una cadena produce cadenas de un carácter, pero chr() convierte un punto de código entero en un carácter Unicode, por lo que cada carácter que produce el bucle es rechazado:

try:
    for char in "42":
        print(chr(char))
except TypeError as error:
    print(f"{type(error).__name__}: {error}")

TypeError: 'str' object cannot be interpreted as an integer

La misma clase de error, con una redacción distinta. En ambos casos la corrección empieza igual: encuentra el argumento que no es un entero.

Cómo diagnosticar el valor pasado a la función

Lee el traceback de abajo hacia arriba. La última línea indica el tipo de excepción y el mensaje; la línea justo encima muestra la llamada que falló. A partir de ahí, rastrea el argumento hasta su origen —una variable de bucle, input(), un archivo de configuración o un campo de cadena JSON— porque los valores leídos como texto llegan como cadenas, mientras que los formatos analizados como JSON ya pueden producir valores con tipo.

Cuando el mensaje no nombra el valor que pasaste, inspecciónalo en el punto de la llamada imprimiendo repr() y type():

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

for char in "42":
    print(f"{char!r} has type {type(char).__name__}; its code point is {ord(char)}")

'4' has type str; its code point is 52
'2' has type str; its code point is 50

Ahora el desajuste es visible: el bucle entrega a chr() la cadena '4' (tipo str), mientras que ord() revela el entero con el que realmente trabaja: el punto de código 52. Una vez que puedes nombrar el tipo y el valor reales del argumento, elegir la corrección adecuada es sencillo.

Cómo corregir la entrada de forma segura

Adapta la corrección a lo que pretendías:

• Para imprimir dígitos o caracteres de una cadena, imprime el valor directamente: print(char) no necesita ninguna llamada a chr().
• Para obtener el carácter almacenado en un punto de código dado, pasa a chr() un entero real. ord() devuelve el punto de código de un carácter y int() convierte una cadena de dígitos en el número que nombra. Ejecuta este ejemplo:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

for char in "42":
    print(char, "->", chr(ord(char)))

4 -> 4
2 -> 2

Para parámetros como maxlen que provienen de un archivo de configuración o de la línea de comandos, convierte el texto una sola vez con int() antes de la llamada y pasa el resultado.

int() solo acepta cadenas que parecen números enteros. Para entradas no confiables, compruébalas primero con str.isdigit() para que un valor incorrecto nunca llegue a la conversión:

text = "53"

if text.isdigit():
    print(chr(int(text)))
else:
    print("not a whole number")

5

Cuando una comprobación no basta, gestiona directamente el fallo de conversión. int() sobre una cadena inadecuada lanza ValueError, una excepción distinta del TypeError con el que empezaste:

try:
    number = int("10.5")
except ValueError as error:
    print(f"{type(error).__name__}: {error}")

ValueError: invalid literal for int() with base 10: '10.5'

Cómo verificar la corrección y evitar errores de tipo relacionados

Vuelve a ejecutar el código y lee la última línea de cualquier traceback restante: te dirá si todavía tienes un problema de tipos o si has pasado a un error diferente. Con maxlen pasado como entero, el fallo anterior se convierte en un deque que funciona:

El código y las etiquetas o salidas visibles de esta sección se mantienen en inglés.

from collections import deque

queue = deque(["x", "y", "z"], maxlen=3)
queue.append("w")
print(list(queue))

['y', 'z', 'w']

Ten en cuenta estos puntos:

• Ajusta el tipo de cada argumento a la firma: chr() toma un punto de código entero, ord() toma un carácter y int() convierte una cadena numérica en un entero.
• Un ValueError de int() no es el TypeError con el que empezaste: capturar uno no ocultará el otro, así que gestiona cada uno en su propio origen.
• Mensajes como can only concatenate o unsupported operand type(s) describen la mezcla de tipos en una expresión, no un argumento incorrecto; necesitan una corrección diferente.

El error es una señal, no un callejón sin salida: una vez que sabes qué valor llevaba el tipo incorrecto, la conversión correcta —o ninguna conversión— suele deducirse directamente.