Troubleshoot Serverless Workers

SUPPORT, STABILITY, and DEPENDENCY INFO

Serverless Workers are in Pre-release.

APIs are experimental and may be subject to backwards-incompatible changes.

This page walks through the Serverless Worker invocation flow and helps you identify where a failure is occurring.

When a Serverless Worker invocation works correctly, the following sequence happens:

1. A Task arrives on a Task Queue.
2. The server associates the Task Queue with a Worker Deployment Version that has a compute provider configured.
3. The Worker Controller Instance (WCI) Workflow detects the backlog via the PullStats Activity.
4. The WCI invokes the Lambda function.
5. The Lambda function starts, the Worker connects to Temporal and polls the Task Queue.
6. The Worker processes Tasks and shuts down gracefully.

Start by determining whether the Lambda function is being invoked at all, then narrow down from there.

Is the Lambda function being invoked?

Check the Lambda function's CloudWatch metrics or invocation logs.

In the AWS Console, go to Lambda > Functions > your function > Monitor. Look for recent invocations in the Invocations graph. You can also check CloudWatch > Log groups > /aws/lambda/your-function-name for execution logs.

If there are no invocations, continue to Lambda is not being invoked.

If the Lambda is being invoked but Workflows are not progressing, skip to Lambda is invoked but Tasks are not completing.

Lambda is not being invoked

Work through the following checks in order. Each check corresponds to a step in the invocation flow.

Check that the WCI Workflow is running

The Worker Controller Instance (WCI) is a system Workflow in the same Namespace as your Worker Deployment that monitors Task Queue backlogs and invokes your Lambda function. One WCI Workflow runs per Worker Deployment Version that has a compute provider configured.

List WCI Workflows in your Namespace:

temporal workflow list \
  --namespace <NAMESPACE> \
  --query 'TemporalNamespaceDivision = "TemporalWorkerControllerInstance"'

Look for a Workflow ID that matches your deployment name and build ID. WCI Workflow IDs follow the pattern temporal-sys-worker-controller-instance:<deployment-name>:<build-id>.

If no WCI Workflow exists for your Worker Deployment Version, the compute provider configuration may not have been applied. Verify the Worker Deployment Version has a compute provider configured:

temporal worker deployment describe \
  --namespace <NAMESPACE> \
  --name <DEPLOYMENT_NAME>

A common cause of a missing WCI is manually invoking the Lambda function before running creating the Worker Deployment Version in the UI or CLI. When the Lambda runs, the Worker connects to Temporal and polls the Task Queue. That polling registers the Worker Deployment Version and binds the Task Queue on the server, but the version has no compute provider and no IAM configuration needed to invoke the Lambda. Without a compute provider, no WCI Workflow is created and the Lambda is never automatically invoked.

To fix the issue, run temporal worker deployment create-version with the compute provider flags as described in the deploy guide, or edit the Worker Deployment Version configuration in the UI by providing the correct compute provider details.

Check that the WCI is detecting Tasks

If the WCI Workflow is running but the Lambda is not being invoked, inspect the WCI's recent Activity.

View the WCI Workflow history:

temporal workflow show \
  --namespace <NAMESPACE> \
  --workflow-id 'temporal-sys-worker-controller-instance:<DEPLOYMENT_NAME>:<BUILD_ID>'

The WCI runs a PullStats Activity on a regular interval (typically every 5 minutes when idle). If PullStats consistently returns no Tasks, the server does not associate any Task Queues with your Worker Deployment Version.

Check which Task Queues are bound to the Worker Deployment Version and whether there is a backlog:

temporal worker deployment describe-version \
  --namespace <NAMESPACE> \
  --deployment-name <DEPLOYMENT_NAME> \
  --build-id <BUILD_ID> \
  --report-task-queue-stats

If no Task Queues are listed, the binding has not been established. The server binds a Task Queue to a Worker Deployment Version when a Worker with that deployment version polls the Task Queue. If the Lambda has never been successfully invoked, or the deployment name or build ID in the Worker code does not match the WCI configuration, the binding does not exist. See Check that the deployment name and build ID match for how to diagnose a mismatch.

Check that the deployment name and build ID match

The deployment name and build ID in your Worker code must exactly match the values in the Worker Deployment Version configuration.

Compare the values in your Lambda function code:

// Go
lambdaworker.RunWorker(worker.WorkerDeploymentVersion{
    DeploymentName: "my-app",
    BuildID:        "build-1",
}, ...)

# Python
run_worker(
    deployment_version=WorkerDeploymentVersion(
        deployment_name="my-app",
        build_id="build-1",
    ),
    ...
)

// TypeScript
runWorker({ deploymentName: 'my-app', buildId: 'build-1' }, ...)

Against the values in the WCI Workflow ID (temporal-sys-worker-controller-instance:<deployment-name>:<build-id>) and the output of temporal worker deployment describe.

A mismatch means the Worker registers with one Worker Deployment Version while the WCI monitors a different one. The server never associates the Task Queue with the WCI's Worker Deployment Version, so PullStats never sees Tasks.

Check IAM permissions for Lambda invocation

If the WCI detects Tasks but the Lambda is not invoked, the issue is likely an IAM permission problem.

Verify that the invocation role trust policy allows Temporal to assume the role. Check for the following common issues:

• The invocation role ARN in the Worker Deployment Version configuration is incorrect.
• The trust policy does not allow the Temporal Cloud account to assume the role.
• The External ID in the trust policy does not match the External ID in the Worker Deployment Version configuration.
• The invocation role does not have lambda:InvokeFunction permission for the Lambda function ARN.

For the correct IAM configuration, see Create an invocation role.

Check the Lambda function ARN

Verify that the Lambda function ARN in the Worker Deployment Version configuration points to an existing function.

aws lambda get-function \
  --function-name <LAMBDA_FUNCTION_ARN>

If you are using a versioned ARN (with a version number or alias suffix), confirm the version or alias exists and points to the correct code.

Lambda is invoked but Tasks are not completing

If CloudWatch shows Lambda invocations but Workflows are not progressing, the problem is in the Worker's execution within the Lambda function.

Check Lambda execution logs

Check CloudWatch logs for errors during Worker startup. In the AWS Console, go to CloudWatch > Log groups > /aws/lambda/your-function-name and look for recent error messages.

Common errors include:

• Connection failures: The Worker cannot reach the Temporal Service. Check that the TEMPORAL_ADDRESS and TEMPORAL_API_KEY environment variables (or temporal.toml config file) are correctly set on the Lambda function. For self-hosted deployments, verify network reachability.
• TLS errors: The TLS certificate or key is missing, expired, or does not match the Namespace.
• Authentication errors: The API key is invalid or does not have access to the Namespace.

Check for Lambda timeout

If the Lambda function reaches its configured timeout before the Worker finishes processing, AWS terminates the invocation.

The Worker begins graceful shutdown before the Lambda deadline. If Activities take longer than the available execution window, the Activities are abandoned mid-execution and retried on the next invocation.

For long-running Activities, increase the Lambda timeout and the Worker's shutdown buffer together. See Tuning for long-running Activities for guidance on how these values relate.

Check for infinite invocation loops

If CloudWatch shows rapid, repeated invocations with no Workflow progress, you may have a build ID mismatch.

This happens when the Lambda function code is updated but the build ID in the Worker code is not changed to match a new Worker Deployment Version. The WCI invokes the Lambda, the Worker starts with the old build ID, the server rejects the poll because the build ID does not match the Worker Deployment Version, and the WCI invokes the Lambda again.

To fix the loop, ensure the build ID in the Worker code matches the build ID in the Worker Deployment Version configuration. See the Lambda versioning caution for details.