# aws lambda update-alias

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws lambda update-alias --function-name my-function --name live --function-version 8 moves the alias to version 8; anything invoking the alias ARN switches immediately. Add --routing-config to send a percentage of traffic to a second version for a canary, and run the same command with the previous number to roll back.

## What the command does

An alias is a named pointer to a function version. Triggers, API Gateway integrations and other services that reference `my-function:live` follow the alias, so moving it is how you release and roll back without reconfiguring callers. The change applies to new invocations straight away; in-flight invocations finish on the version they started with.

## Syntax

```
aws lambda update-alias --function-name my-function --name live \
  [--function-version 8] \
  [--routing-config '{"AdditionalVersionWeights": {"9": 0.1}}'] \
  [--description "..."] [--revision-id ...]
```

The alias must already exist; create it with `aws lambda create-alias`.

## Worked examples

**Release version 8:**

```
aws lambda update-alias --function-name my-function --name live --function-version 8
```

**Roll back**: find the previous version and point the alias back. The backslash before `$LATEST` stops the shell expanding it as a variable:

```
aws lambda list-versions-by-function --function-name my-function \
  --query "Versions[?Version!='\$LATEST'].[Version,LastModified,Description]" --output table
aws lambda update-alias --function-name my-function --name live --function-version 7
```

**Canary**: keep version 8 as primary and send 10% of invocations to version 9:

```
aws lambda update-alias --function-name my-function --name live \
  --function-version 8 \
  --routing-config '{"AdditionalVersionWeights": {"9": 0.1}}'
```

Watch errors for both versions; the `ExecutedVersion` field and the version-specific metrics show which version handled each request.

**Complete the rollout**: make 9 primary and clear the weights:

```
aws lambda update-alias --function-name my-function --name live \
  --function-version 9 --routing-config '{"AdditionalVersionWeights": {}}'
```

**Confirm**:

```
aws lambda get-alias --function-name my-function --name live \
  --query "[FunctionVersion,RoutingConfig]" --output json
```

## Options

| Option | Notes |
|---|---|
| `--function-version` | The primary version. A number, or `$LATEST` (not allowed when weighted routing is used). |
| `--routing-config` | One extra version and its weight, between 0 and 1. The primary gets the remainder. |
| `--revision-id` | Fails the update if the alias changed since you read it; useful in pipelines. |

## Gotchas

- **Routing config persists.** Changing only `--function-version` keeps the existing weights. Clear them explicitly when the canary is done.
- **Provisioned concurrency** is configured on the alias or version. Moving an alias to a version without warm capacity can cause cold starts.
- **Permissions follow the alias.** A resource-policy statement added with `--qualifier live` stays valid when the alias moves.
- **Event source mappings** attached to the alias ARN start using the new version for new batches; one attached to the unqualified ARN is not affected at all.
- **Use CodeDeploy for automated canaries** with alarms and automatic rollback; manual weights are fine for quick checks.
- **Function URLs on an alias follow it.** A function URL created with the alias as its qualifier serves whichever version the alias points to, so moving the alias also changes what the URL returns.
- **Record what you changed.** Note the previous version before moving the alias; rolling back is only instant if you know which number was good.

## Questions

### How do I roll back a Lambda function?

Point its alias back at the previous version with update-alias --function-version. This is instant and does not redeploy code.

### How do I split traffic between two Lambda versions?

Use --routing-config '{"AdditionalVersionWeights": {"9": 0.1}}' with update-alias to send 10% of traffic to version 9.

### Can an alias point to $LATEST?

Yes, but then it moves with every deploy, and weighted routing is not available. Aliases are most useful when they point at published versions.

## When this happens away from your desk

Rolling an alias back is one of the fastest fixes for a bad Lambda release. CloudConsole, a phone app for AWS, is built to show the error alarm and recent versions on a phone, with production guardrails before any change.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: lambda update-alias](https://docs.aws.amazon.com/cli/latest/reference/lambda/update-alias.html)
- [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)

## Related

- [How to roll back a Lambda version](https://cloudconsole.dev/how-to/roll-back-lambda-version)
- [aws lambda publish-version](https://cloudconsole.dev/cli/lambda-publish-version)
- [aws lambda list-versions-by-function](https://cloudconsole.dev/cli/lambda-list-versions-by-function)
- [aws lambda invoke](https://cloudconsole.dev/cli/lambda-invoke)
- [CloudWatch alarm: Lambda Errors](https://cloudconsole.dev/alarms/lambda-errors)
- [aws lambda add-permission](https://cloudconsole.dev/cli/lambda-add-permission)

---

Source: https://cloudconsole.dev/cli/lambda-update-alias

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
