> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debugging AWS Lambda

> Separate function deployment, synchronous invocation transport, handler outcomes and retries.

A function can be deployed but not ready to receive a request. A successful synchronous Invoke transport can carry a handler error. Current Cloud Adapter Lambda profiles do not serve asynchronous `Event` invocation. Start by identifying the failing state and the supported request form, rather than invoking the function repeatedly until one request succeeds.

Record the origin function name or ARN exactly as sent, account and region, adapter version, selected target profile, code artifact and invocation type. Use the [Lambda service profile](https://docs.tensor9.com/cloud-adapter/service-catalog/aws/compute-containers/lambda-function.md) for operation and packaging coverage. Cloud Run, Azure Functions, Container Apps, Knative, Kubernetes and other targets have different deployment, networking and logging models.

## Separate deployment from invocation

| Observation | What it establishes | What still needs checking |
| - | - | - |
| Create or update was accepted | Desired function configuration was admitted | Native deployment and readiness. |
| Configuration reports ready | The lifecycle considers the function available | Routing, caller permission and handler behavior. |
| Synchronous Invoke returned a response | The request received a transport-level result | `FunctionError`, payload and application effects. |
| `Event` invocation was refused | The request is outside current Cloud Adapter Lambda profile coverage | Whether the application requires a separately supported asynchronous contract. |
| An explanation is sealed | Diagnostic collection ended | The report's actual operation state and limitations. |

Do not turn one state into proof of another. In particular, changing a function's memory or timeout does not repair a route to the wrong deployment.

## Inspect configuration without invoking

For a profile that serves `GetFunctionConfiguration`, use the origin endpoint and the caller's normal IAM credentials. Set `LAMBDA_ENDPOINT`, `AWS_REGION` and `FUNCTION_NAME` to the deployment being investigated:

```bash theme={null}
aws lambda get-function-configuration \
  --endpoint-url "$LAMBDA_ENDPOINT" \
  --region "$AWS_REGION" \
  --function-name "$FUNCTION_NAME" \
  --query '{FunctionName:FunctionName,State:State,LastUpdateStatus:LastUpdateStatus,LastUpdateStatusReasonCode:LastUpdateStatusReasonCode,Version:Version,Runtime:Runtime,Timeout:Timeout,MemorySize:MemorySize}' \
  --output json
```

This read does not run the handler. It still follows the adapter's configured Explain default; a preview refusal is not function-configuration data. Record unavailable fields as unavailable. The [AWS command reference](https://docs.aws.amazon.com/cli/latest/reference/lambda/get-function-configuration.html) describes the origin API; the selected adapter profile determines which forms it implements.

Compare the returned configuration with the intended artifact and target deployment. Read native revision readiness, startup failures and configured identity through the deployment owner. A native URL copied from an old revision is not evidence that the origin function currently resolves there.

Treat qualifiers explicitly. The current Invoke route rejects alias- or version-qualified calls, and the current configuration route serves `$LATEST` rather than a full published-version contract. Confirm coverage for the installed profile. Do not silently remove a production qualifier to make a request succeed: that changes which function the caller intended to address.

## Classify invocation failures

**A modeled API error before execution** can indicate invalid signing, an unknown function, a mismatched account or region, unsupported request options, permission refusal or unavailable routing. Preserve the status and error code. Check `lambda:InvokeFunction` authorization separately from the target runtime's own permissions.

**A synchronous `RequestResponse` result** requires inspecting both response metadata and payload. HTTP success alone does not establish handler success; `FunctionError` identifies a handler failure. Record `ExecutedVersion` when supplied, but use the artifact and native revision to identify deployed code. A `$LATEST` label is not an immutable image digest. AWS documents the distinction between API status and function errors in the [Invoke reference](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html).

**An asynchronous `Event` request is unsupported by current Cloud Adapter Lambda profiles.** Native AWS supports that invocation type, but the selected adapter profiles list it as out of scope. Do not treat an AWS-native acceptance response or private implementation code as evidence of supported adapter delivery. If the application requires asynchronous invocation, resolve that capability requirement explicitly; changing its client to `RequestResponse` changes the application's contract.

The current Invoke path also rejects `LogType=Tail`. Do not add that option merely to obtain debugging output. Use the selected target's approved log access and supported diagnostics; a profile must explicitly establish broader log-tail support.

## Correlate logs with the same attempt

Keep the origin request ID, invocation type, logical application job ID, function identity and time window. Add the native request or revision identifier when available. Correlate those values with the selected target's runtime logs and the application's result store.

Separate an image-pull or initialization failure from a handler exception and from a downstream API refusal. The caller's IAM permission to invoke does not grant the function access to an object, secret or database. A handler can start successfully and then fail under its own runtime identity.

Do not assume CloudWatch log groups exist for a function hosted elsewhere. Read the profile's logging integration and native runtime observations. Avoid dumping complete payloads, environment variables or authorization headers into a ticket; logs can contain customer data and credentials.

## Compare Cloud Run and Azure Container Apps

The examples below investigate an existing synchronous `RequestResponse` attempt on two catalog container-image mappings. They do not send another Invoke. Record the logical function, exact artifact/image identity, selected profile, native service/revision and original request time. Neither profile's public contract includes `Event` invocation, aliases or a general published-version Invoke surface.

### Cloud Run: a caller deadline is not handler termination

For **Lambda → Google Cloud Run**, the function is packaged as a container image and routed to its mapped Cloud Run service. The profile configures one request per instance and maps the function timeout to a native request deadline. With the mapped service identity, the target operator can inspect its configuration without invoking:

```bash theme={null}
gcloud run services describe "$RUN_SERVICE" --region "$GCP_REGION" \
  --project "$GCP_PROJECT" --format=json
```

Compare deployed image/revision, traffic assignment and request timeout with the original function configuration and request window. Suppose native request evidence shows a timeout while the handler's result ledger later records completion. That is consistent with [Cloud Run's documented behavior](https://docs.cloud.google.com/run/docs/configuring/request-timeout): returning a timeout does not terminate the container. Preserve the completed application job and avoid an automatic duplicate invocation. Diagnose the handler's downstream wait or cancellation behavior before increasing the timeout or replaying work. A successful configuration read alone cannot establish this outcome; it must agree with that attempt's native logs and result record.

### Container Apps: distinguish deployment health from worker admission

For **Lambda → Azure Container Apps**, the catalog also requires a container image, but Tensor9's adapter owns single-request admission per worker. Azure Container Apps scales the replica fleet; it does not supply the same one-request-per-instance contract as this Cloud Run profile. Inspect the mapped revision through the target operator's Azure identity:

```bash theme={null}
az containerapp revision show --resource-group "$RESOURCE_GROUP" \
  --name "$CONTAINER_APP" --revision "$REVISION_NAME" --output json
```

Use the revision selected for the failed attempt, not merely the newest revision. Azure's [deployment troubleshooting guide](https://learn.microsoft.com/en-us/azure/container-apps/troubleshoot-deployment-errors) distinguishes unhealthy/degraded revisions, image pull failures and probe failures. If that revision never became healthy, inspect those deployment events before retrying the function. If it is healthy and failures occur only during a burst, compare replica availability, configured worker count and admission/rejection observations for the same interval. More retries can amplify contention.

Illustrative result: no handler-start or business-result evidence exists for a refused burst attempt, while another attempt completed. Keep those outcomes separate. Do not infer an empty effect history from a caller timeout: this profile's connection backstop does not guarantee remote handler termination either. Review any subsequent retry against the application's job ledger and duplicate handling. Do not “fix” either example by switching to `Event`, which is outside current public profile support.

## Worked case: HTTP success, failed handler

Suppose an existing synchronous call to `thumbnail-worker` returned HTTP `200`, `FunctionError: Unhandled` and a payload indicating that an input-object read was denied.

1. Preserve that response and the application job ID. Do not count it as a successful thumbnail solely because transport returned `200`.
2. Read function configuration without invoking. Confirm the intended artifact, ready state, timeout and memory; inspect the native revision selected for the function.
3. Find the same attempt in native logs. Verify whether the refusal occurred under the function's storage identity, rather than under the original caller's invocation identity.
4. Inspect the application's job ledger and expected output object using authorized reads. The error does not by itself prove that no earlier side effect happened.
5. Have the resource owner review the precise permission or mapping. Any permission change and subsequent test invocation is a separate approved action. Keep the same logical job identity and verify duplicate handling before retrying work.

This investigation distinguishes routing, runtime permission and application completion without using another invocation as a status probe.

## Keep retries and Explain scoped

List the retry sources actually present: client/SDK transport retries, application retries and upstream caller retries. They can overlap. Do not assume native AWS asynchronous-delivery retries apply to an adapter that does not serve `Event`. A response timeout does not prove that a handler stopped; consult the result store before repeating a job and use application-level idempotent commits. An invocation API is not a universal exactly-once mechanism.

For a supported path, [request Explain](https://docs.tensor9.com/cloud-adapter/debugging/explain-sdk.md) can help identify the selected route and captured attempt. Invocation Explain and function-lifecycle Explain have separate coverage. Current executing Invoke capture is restricted to qualified synchronous, identity-authorized routed paths. Current Cloud Adapter profiles do not provide `Event` invocation or executing Explain for it. Retrieve an existing receipt through the dedicated `t9` service as the original report owner. Polling the report does not invoke the function.

The [planned PostgreSQL plan guide](https://docs.tensor9.com/cloud-adapter/debugging/postgres-query-plans.md) applies only to instrumented SQL actually reached by that adapter. A function's arbitrary application database queries are not automatically collected. Full plans can include sensitive expressions, so sanitize any exported copy.

Share configuration and artifact identities, the native response, handler error, retry history, correlated logs and independently observed effects through [Getting Help](https://docs.tensor9.com/cloud-adapter/support/getting-help.md). Use [Lambda tuning](https://docs.tensor9.com/cloud-adapter/tuning/aws-lambda.md) after identifying the failing stage.

Use a [Support Agent](https://docs.tensor9.com/cloud-adapter/support/agents.md) to compare the original invocation, native revision and business-result evidence before deciding whether another invocation is safe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.