Aumentar el Timeout de Lambda: Configuración, Límites y Diagnóstico en Producción

Tu función Lambda se detiene a los 3 segundos, pero el proceso que ejecuta necesita 10. No es un bug en tu código — es el timeout por defecto de Lambda actuando exactamente como fue diseñado. El problema es que ese valor predeterminado de 3 segundos sorprende a casi todos la primera vez, especialmente cuando la función funciona perfectamente en local pero falla en producción con un error Task timed out after 3.00 seconds.

TL;DR — Aumentar el Timeout de Lambda

Aspecto	Detalle
Timeout por defecto	3 segundos
Timeout máximo	15 minutos (900 segundos)
Dónde configurarlo	Consola AWS, CLI, CloudFormation, SAM, Terraform
Error observable	`Task timed out after X.XX seconds`
Coste asociado	Mayor timeout = mayor ventana de facturación potencial
Alternativa para tareas largas	AWS Step Functions o procesamiento asíncrono

Cómo Funciona el Timeout en AWS Lambda

Lambda ejecuta tu función dentro de un entorno de ejecución gestionado. Cuando invocas una función, el servicio inicia un temporizador en el momento en que el handler comienza a ejecutarse. Si ese temporizador llega al valor configurado antes de que el handler retorne, Lambda termina el proceso de forma forzada y registra el error de timeout en CloudWatch Logs.

Este comportamiento es determinista: Lambda no espera, no reintenta automáticamente por timeout en invocaciones síncronas, y no lanza una excepción que puedas capturar dentro del handler. El proceso simplemente muere.

graph TD A["Invocación Lambda"] --> B["Handler inicia
Temporizador arranca"] B --> C{"¿Handler completa
antes del timeout?"} C -->|"Sí"| D["Respuesta retornada
Temporizador detenido"] C -->|"No"| E["Proceso terminado
forzosamente"] E --> F["CloudWatch Log:
Task timed out after X.XX seconds"] D --> G["REPORT log escrito
con duración real"]

Invocación: El cliente o servicio invoca la función Lambda.
Inicio del temporizador: Lambda inicia el contador de timeout en cuanto el handler comienza.
Ejecución normal: Si el handler completa antes del límite, Lambda retorna la respuesta y detiene el temporizador.
Timeout alcanzado: Si el temporizador expira, Lambda termina el proceso forzosamente y escribe el error en CloudWatch Logs.
Error registrado: El log muestra Task timed out after X.XX seconds.

Pensar en el timeout de Lambda como un fusible eléctrico ayuda: no protege tu código de errores, protege al sistema de funciones que se quedan colgadas indefinidamente consumiendo recursos y generando costes.

Dónde Cambiar el Timeout de Lambda — Todas las Opciones

Hay cuatro formas documentadas de modificar el timeout. Todas escriben el mismo atributo de configuración de la función; la diferencia es el mecanismo de despliegue que uses.

Opción 1: Consola de AWS

Navega a Lambda → tu función → Configuration → General configuration → Edit. El campo 'Timeout' acepta minutos y segundos por separado. El cambio es inmediato y no requiere redespliegue del código.

Opción 2: AWS CLI

Esta es la forma más directa para cambiar el timeout en automatizaciones o pipelines CI/CD. El parámetro --timeout acepta el valor en segundos.

aws lambda update-function-configuration \
  --function-name mi-funcion \
  --timeout 30

Para verificar el valor actual antes de modificarlo:

aws lambda get-function-configuration \
  --function-name mi-funcion \
  --query 'Timeout'

Opción 3: AWS SAM (serverless application model)

En el template SAM, el timeout se define a nivel de recurso o como propiedad global:

🔽 Ver template SAM con timeout configurado

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Globals:
  Function:
    Timeout: 30

Resources:
  MiFuncion:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      Timeout: 60  # Sobreescribe el global para esta función
      CodeUri: src/

Opción 4: CloudFormation

MiFuncionLambda:
  Type: AWS::Lambda::Function
  Properties:
    FunctionName: mi-funcion
    Handler: index.handler
    Runtime: nodejs20.x
    Timeout: 60
    Role: !GetAtt LambdaExecutionRole.Arn
    Code:
      S3Bucket: mi-bucket-despliegue
      S3Key: funcion.zip

Límite Máximo de Timeout en Lambda

El timeout máximo documentado por AWS para una función Lambda es de 900 segundos (15 minutos). Este es un límite de servicio fijo, no configurable por cuenta ni por región.

Si tu tarea requiere más de 15 minutos, Lambda no es la herramienta correcta para ese paso. Las alternativas documentadas incluyen AWS Step Functions con estados de tarea de larga duración, AWS Batch, o ECS Fargate para cargas de trabajo de procesamiento prolongado.

Diagnóstico: Tu Función Sigue Fallando por Timeout

Aumentaste el timeout a 30 segundos, redespliegaste, y el error persiste. Antes de subirlo más, vale la pena confirmar que el cambio se aplicó correctamente y que el timeout es realmente la causa raíz.

Paso 1: Confirmar que el timeout actualizado está activo

Existe una ventana corta después de update-function-configuration durante la cual Lambda muestra el estado LastUpdateStatus: InProgress. Invocar la función en ese intervalo puede ejecutar la versión anterior. Verifica el estado antes de probar:

aws lambda get-function-configuration \
  --function-name mi-funcion \
  --query '{Timeout: Timeout, LastUpdateStatus: LastUpdateStatus}'

El valor de LastUpdateStatus debe ser Successful antes de continuar.

Paso 2: Leer el log de CloudWatch correctamente

El error de timeout aparece al final del stream de logs de la invocación fallida, no al principio. Busca la línea exacta que Lambda escribe:

aws logs filter-log-events \
  --log-group-name '/aws/lambda/mi-funcion' \
  --filter-pattern 'Task timed out' \
  --start-time $(date -d '1 hour ago' +%s000)

Si ves Task timed out after 30.00 seconds cuando configuraste 30 segundos, el cambio sí se aplicó — tu tarea simplemente necesita más tiempo del estimado.

Paso 3: Medir el tiempo real de ejecución con el REPORT log

Lambda escribe automáticamente una línea REPORT al final de cada invocación exitosa con la duración real. Para invocaciones que completan antes del timeout, este valor te da la línea base real:

aws logs filter-log-events \
  --log-group-name '/aws/lambda/mi-funcion' \
  --filter-pattern 'REPORT RequestId' \
  --start-time $(date -d '1 hour ago' +%s000) \
  --query 'events[*].message'

La línea REPORT incluye Duration, Billed Duration, y Max Memory Used. Si la duración real es consistentemente cercana al timeout configurado, estás ajustando el límite sin entender la causa raíz.

Paso 4: Verificar si hay un timeout de integración upstream bloqueando antes que Lambda

Este es el punto donde la mayoría falla. Si tu Lambda está detrás de API Gateway, el timeout máximo de integración de API Gateway es de 29 segundos. Configurar Lambda a 60 segundos no resuelve nada si API Gateway corta la conexión a los 29 segundos — el cliente recibe un 504 Gateway Timeout y Lambda puede seguir ejecutándose en background hasta que su propio timeout expire.

aws apigateway get-integration \
  --rest-api-id tu-api-id \
  --resource-id tu-resource-id \
  --http-method POST \
  --query 'timeoutInMillis'

Si el resultado es 29000 (el máximo documentado para API Gateway REST), necesitas rediseñar el flujo para que sea asíncrono, no simplemente aumentar el timeout de Lambda.

graph LR Cliente["Cliente HTTP"] --> APIGW["API Gateway
Timeout máx: 29s"] APIGW --> Lambda["Lambda
Timeout máx: 900s"] Lambda --> DB["Base de datos
/ API externa"] APIGW -->|"504 a los 29s"| ClienteError["Cliente recibe error"] Lambda -->|"Continúa hasta
su propio timeout"| LambdaLog["CloudWatch Log
puede mostrar éxito"]

API Gateway timeout: Máximo 29 segundos. Si Lambda tarda más, el cliente recibe 504 aunque Lambda complete correctamente.
Lambda timeout: Máximo 900 segundos. Opera independientemente del timeout de API Gateway.
Zona de conflicto: Entre 29s y 900s, Lambda puede completar pero el cliente ya recibió un error.

El Error que Todos Cometen: Subir el Timeout sin Medir

La secuencia real que ocurre en producción: la función falla con timeout, el desarrollador sube el valor de 3 a 30 segundos, el error desaparece, y nadie investiga por qué la tarea tarda 25 segundos.

Tres semanas después, hay una llamada a una API externa que empieza a responder lento, la función empieza a tardar 28 segundos consistentemente, y el timeout de 30 segundos ya no tiene margen. El problema real era una consulta a base de datos sin índice que tardaba 20 segundos — el timeout aumentado simplemente ocultó el síntoma.

Antes de subir el timeout, mide la duración real con el REPORT log e identifica qué operación consume el tiempo. El timeout correcto es el tiempo real de la tarea más un margen razonable — no el valor más alto que el servicio permite.

Permisos IAM Necesarios para Modificar el Timeout

Para ejecutar update-function-configuration desde un rol o usuario IAM, la política debe incluir la acción correspondiente. La acción opera a nivel de función específica:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunctionConfiguration"
      ],
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:mi-funcion"
    }
  ]
}

Para leer logs de CloudWatch en el diagnóstico, el rol también necesita permisos sobre el log group de la función:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:FilterLogEvents",
        "logs:GetLogEvents"
      ],
      "Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/mi-funcion:*"
    }
  ]
}

Cuándo el Timeout de Lambda No Es la Solución

Si tu tarea supera consistentemente los 5-10 minutos, o si necesita procesar volúmenes variables de trabajo, aumentar el timeout de Lambda es un parche, no una arquitectura. Las señales de que necesitas repensar el diseño:

La tarea procesa archivos grandes desde S3 cuyo tamaño varía significativamente.
El tiempo de ejecución depende de la carga de una base de datos externa.
Necesitas reintentar pasos individuales sin reiniciar todo el proceso.
La tarea debe ejecutarse por más de 15 minutos en casos extremos.

Para estos casos, AWS Step Functions permite orquestar múltiples invocaciones Lambda con estado persistente, reintentos por paso, y tiempos de espera de hasta un año para flujos de aprobación humana.

Aumentar el Timeout de Lambda — Próximos Pasos

El cambio en sí tarda menos de un minuto. La parte que vale tiempo es entender por qué tu función necesita ese tiempo y si Lambda es el servicio correcto para esa duración.

Documentación oficial: Configuring Lambda function timeout — AWS Documentation
Si usas API Gateway, revisa los límites de timeout de integración en la documentación de API Gateway antes de asumir que Lambda es el cuello de botella.
Para tareas de larga duración, evalúa el patrón de invocación asíncrona de Lambda con destinos de eventos (EventInvokeConfig) como alternativa antes de migrar a Step Functions.

Glosario

Término	Definición
Timeout de función	Tiempo máximo en segundos que Lambda permite ejecutar el handler antes de terminar el proceso forzosamente.
REPORT log	Línea que Lambda escribe automáticamente al final de cada invocación con duración real, duración facturada y memoria usada.
Task timed out	Mensaje de error que Lambda registra en CloudWatch cuando el handler supera el timeout configurado.
LastUpdateStatus	Campo en la configuración de Lambda que indica si el último cambio de configuración completó correctamente (`Successful`) o está en progreso (`InProgress`).
Invocación asíncrona	Modo de invocación Lambda donde el cliente recibe confirmación inmediata y Lambda procesa el evento en background, desacoplando el timeout del cliente del timeout de la función.

Buscar este blog

SW BBANG E