Lambda Timeout erhöhen: Konfiguration, Maximum und häufige Fallstricke

Eine Lambda-Funktion bricht nach 3 Sekunden ab, obwohl die eigentliche Verarbeitung 10 Sekunden benötigt — dieses Problem taucht regelmäßig auf, wenn Entwickler den Standard-Timeout übersehen und erst im Produktionsbetrieb merken, dass Tasks still abgebrochen werden, ohne einen aussagekräftigen Fehler zu hinterlassen.

TL;DR: Lambda Timeout schnell verstehen

Aspekt	Detail
Standard-Timeout	3 Sekunden
Maximaler Timeout	900 Sekunden (15 Minuten)
Konfigurationsort	Funktionskonfiguration → Allgemeine Konfiguration
CLI-Parameter	`--timeout` bei `create-function` oder `update-function-configuration`
Häufigste Falle	Timeout auf Funktionsebene erhöht, aber API Gateway hat eigenes 29-Sekunden-Limit

Wie Lambda Timeout funktioniert

Lambda führt jede Funktion in einer isolierten Ausführungsumgebung aus. Der Timeout-Wert definiert die maximale Laufzeit eines einzelnen Invocation-Requests — nicht die Gesamtlaufzeit aller gleichzeitigen Ausführungen. Wird der Timeout überschritten, beendet Lambda die Ausführung hart: laufende Threads werden abgebrochen, kein Cleanup-Code wird ausgeführt, und die Funktion gibt einen Task timed out after X.XX seconds-Fehler zurück.

Dieser Abbruch ist kein Soft-Signal. Es ist ein erzwungener Prozess-Kill. Datenbankverbindungen, offene Sockets oder halbfertige Schreiboperationen werden nicht sauber geschlossen — das ist ein wichtiger operativer Unterschied zu einem normalen Exception-Handling-Pfad.

graph TD A["Invocation startet"] --> B["Timeout-Countdown beginnt"] B --> C{"Funktion fertig vor Timeout?"} C -->|"Ja"| D["Erfolgreiche Antwort"] C -->|"Nein"| E["Lambda bricht Ausführung ab"] E --> F["CloudWatch Log: Task timed out after X.XX seconds"] F --> G{"Aufruftyp?"} G -->|"Synchron"| H["Fehler an Aufrufer zurückgegeben"] G -->|"Asynchron"| I["Retry-Logik greift (je nach Event-Quelle)"]

Invocation: Der Aufruf startet die Ausführungsumgebung und beginnt den Timeout-Countdown.
Normale Beendigung: Die Funktion gibt ein Ergebnis zurück, bevor der Timeout abläuft — Erfolg.
Timeout-Überschreitung: Lambda bricht die Ausführung hart ab und schreibt einen Timeout-Fehler in CloudWatch Logs.
Retry-Verhalten: Abhängig vom Aufruftyp (synchron vs. asynchron) und der Event-Quelle — nicht automatisch bei synchronen Aufrufen.

Lambda Timeout erhöhen: Schritt-für-Schritt

Option 1: AWS Management Console

In der Lambda-Konsole unter Funktionskonfiguration → Allgemeine Konfiguration → Bearbeiten findet sich das Timeout-Feld. Der Wert wird in Sekunden angegeben. Nach dem Speichern gilt die neue Einstellung sofort für alle neuen Invocations — laufende Ausführungen sind nicht betroffen.

Option 2: AWS CLI

Für eine bestehende Funktion reicht ein einzelner CLI-Aufruf:

aws lambda update-function-configuration \
  --function-name meine-funktion \
  --timeout 30 \
  --region us-east-1

Für eine neue Funktion wird --timeout direkt beim Erstellen mitgegeben:

aws lambda create-function \
  --function-name meine-funktion \
  --runtime python3.12 \
  --role arn:aws:iam::123456789012:role/lambda-execution-role \
  --handler index.handler \
  --zip-file fileb://function.zip \
  --timeout 30 \
  --region us-east-1

Den aktuellen Timeout einer Funktion auslesen:

aws lambda get-function-configuration \
  --function-name meine-funktion \
  --region us-east-1 \
  --query 'Timeout'

Option 3: AWS CloudFormation / SAM

Resources:
  MeineFunktion:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: meine-funktion
      Runtime: python3.12
      Handler: index.handler
      Role: arn:aws:iam::123456789012:role/lambda-execution-role
      Timeout: 30
      Code:
        S3Bucket: mein-deployment-bucket
        S3Key: function.zip

Das Maximum und seine Grenzen verstehen

Lambda erlaubt maximal 900 Sekunden (15 Minuten) pro Ausführung. Das ist eine von AWS dokumentierte Hard Limit — es kann nicht per Service-Quota-Erhöhung angehoben werden. Aufgaben, die länger dauern, müssen architektonisch anders gelöst werden: etwa über Step Functions, SQS-basierte Chunking-Strategien oder asynchrone Verarbeitungspipelines.

Lambda ist wie ein Kurzstreckenläufer, kein Marathonläufer. Wer Stunden-lange Batch-Jobs direkt in Lambda steckt, kämpft gegen das Design des Services — nicht gegen einen Konfigurationsfehler.

Lambda Timeout erhöhen reicht nicht immer: Der API-Gateway-Fallstrick

Hier liegt die häufigste Fehlerdiagnose in der Praxis: Der Lambda-Timeout wird auf 60 Sekunden erhöht, aber Aufrufe über API Gateway schlagen weiterhin nach ~29 Sekunden fehl. Der Grund ist, dass API Gateway ein eigenes, nicht konfigurierbares Integrations-Timeout von 29 Sekunden für Lambda-Proxy-Integrationen hat.

Das bedeutet: Selbst wenn Lambda theoretisch länger laufen dürfte, bricht API Gateway die HTTP-Verbindung vorher ab. Die Lambda-Funktion läuft dann im Hintergrund weiter — aber der Client bekommt bereits einen Fehler zurück.

sequenceDiagram participant C as Client participant AG as API Gateway participant L as Lambda C->>AG: HTTP Request AG->>L: Lambda Invoke Note over AG: 29s Integrations-Timeout Note over L: Lambda Timeout (z.B. 60s) alt Antwort innerhalb 29s L-->>AG: Ergebnis AG-->>C: HTTP 200 else Lambda braucht > 29s AG-->>C: HTTP 504 / Timeout-Fehler Note over L: Lambda läuft weiter Note over L: bis eigenem Timeout end

Client-Request: HTTP-Anfrage trifft API Gateway.
API Gateway Limit: API Gateway wartet maximal 29 Sekunden auf eine Antwort von Lambda.
Lambda läuft weiter: Überschreitet die Lambda-Ausführung 29 Sekunden, antwortet API Gateway mit einem Fehler — Lambda selbst läuft bis zu seinem eigenen Timeout weiter.
Lösung: Asynchrones Muster verwenden — API Gateway gibt sofort eine Job-ID zurück, Lambda verarbeitet im Hintergrund.

Wer Tasks über 29 Sekunden via HTTP-Endpunkt auslösen muss, braucht ein asynchrones Muster: Lambda wird mit InvocationType: Event aufgerufen, gibt sofort eine Bestätigung zurück, und der Client pollt einen Status-Endpunkt.

Symptom, Fehldiagnose, eigentliche Ursache: Ein reales Muster

Das Symptom: Eine Lambda-Funktion, die Bilddaten transformiert, schlägt sporadisch fehl. CloudWatch Logs zeigen Task timed out after 3.00 seconds. Der erste Reflex: Timeout auf 30 Sekunden erhöhen. Das behebt das Problem — aber nur für kleine Bilder.

Die Fehldiagnose: 'Der Timeout war zu niedrig.' Stimmt, aber das ist nicht die eigentliche Ursache. Die eigentliche Ursache: Die Funktion lädt das Bild bei jedem Aufruf aus S3, ohne die Ausführungsumgebung für Caching zu nutzen. Bei großen Dateien überschreitet allein der Download-Vorgang den ursprünglichen Timeout. Nach dem Erhöhen des Timeouts läuft die Funktion zwar durch, aber mit unnötig hohen Kosten und Latenz.

Die korrekte Lösung: S3-Download-Logik außerhalb des Handlers in den Initialisierungsbereich verschieben, sodass Warm-Starts den Download überspringen. Timeout-Erhöhung war notwendig, aber nicht hinreichend.

IAM-Berechtigungen für Timeout-Konfiguration

Um den Timeout per CLI oder SDK zu ändern, benötigt die aufrufende Identität die Berechtigung lambda:UpdateFunctionConfiguration. Für reine Lesezugriffe reicht lambda:GetFunctionConfiguration.

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

Timeout-Überwachung mit CloudWatch

Lambda veröffentlicht keine native 'Timeout-Rate'-Metrik, aber Timeout-Fehler sind in CloudWatch Logs als Task timed out erkennbar. Eine Metric Filter auf diese Log-Meldung liefert einen operativen Alarm:

aws logs put-metric-filter \
  --log-group-name /aws/lambda/meine-funktion \
  --filter-name TimeoutFilter \
  --filter-pattern 'Task timed out' \
  --metric-transformations \
      metricName=LambdaTimeouts,metricNamespace=Custom/Lambda,metricValue=1 \
  --region us-east-1

Zusätzlich ist die CloudWatch-Metrik Duration nützlich: Wenn der P99-Wert sich dem konfigurierten Timeout nähert, ist das ein Frühwarnsignal, bevor tatsächliche Timeouts auftreten.

graph LR A["Lambda Ausführung"] --> B["CloudWatch Logs"] A --> C["Duration-Metrik"] B --> D["Metric Filter: Task timed out"] D --> E["Custom Metrik: LambdaTimeouts"] C --> F["P99 Alarm: near Timeout-Wert"] E --> G["CloudWatch Alarm"] F --> G G --> H["SNS Benachrichtigung"]

Duration-Metrik: Zeigt die tatsächliche Ausführungszeit. P99 nahe am Timeout-Wert ist ein Warnsignal.
Metric Filter: Erkennt Timeout-Fehler in Logs und erzeugt eine messbare Metrik.
CloudWatch Alarm: Löst bei Überschreitung des Schwellenwerts eine Benachrichtigung aus.

Wrap-up: Lambda Timeout erhöhen und richtig dimensionieren

Den Lambda Timeout zu erhöhen ist ein einzeiliger CLI-Befehl — aber die richtige Dimensionierung erfordert Verständnis der gesamten Aufrufkette. Timeout auf Funktionsebene, API-Gateway-Limit, asynchrone Muster und Monitoring müssen zusammen betrachtet werden. Wer nur den Lambda-Timeout erhöht, ohne die nachgelagerten Grenzen zu prüfen, löst das Problem möglicherweise nur auf dem Papier.

Für Tasks, die das 15-Minuten-Maximum überschreiten, sind AWS Step Functions oder eine SQS-basierte Verarbeitungsarchitektur die dokumentierten Alternativen.

Glossar

Begriff	Bedeutung
Timeout	Maximale Ausführungszeit einer Lambda-Funktion pro Invocation, konfigurierbar zwischen 1 und 900 Sekunden.
Invocation	Ein einzelner Aufruf einer Lambda-Funktion, synchron oder asynchron.
Cold Start	Erste Ausführung in einer neuen Ausführungsumgebung — beinhaltet Initialisierungszeit, die zum Timeout zählt.
Metric Filter	CloudWatch-Mechanismus, der Log-Einträge nach Mustern durchsucht und daraus Metriken erzeugt.
Asynchroner Aufruf	Lambda-Aufruf mit `InvocationType: Event` — der Aufrufer wartet nicht auf das Ergebnis.

Dieses Blog durchsuchen

SW BBANG D