## TL;DR
A rotation stuck in pending almost always means the rotation Lambda errored and never finished the state machine. Read the Lambda logs, fix the underlying permission or code error, then cancel the stuck rotation and start a fresh one. Never leave an `AWSPENDING` version dangling.

## Steps
1. Inspect the rotation state: run `aws secretsmanager describe-secret` and note the `RotationRules`, `RotationEnabled`, and which version carries the `AWSPENDING` label. Expected: you see the stuck version and how long it has been pending.
2. Read the rotation Lambda logs in CloudWatch for the time window of the stuck rotation. Expected: a concrete error (timeout, access denied, or an exception in the rotation code) instead of a mystery.
3. Fix the root cause: the usual suspects are a missing IAM permission on the Lambda role, a KMS grant, or the Lambda failing to reach the database. Expected: the specific error from step 2 is resolved.
4. Cancel the stuck rotation: run `aws secretsmanager cancel-rotate-secret` for the secret. Expected: the `AWSPENDING` label is removed and the secret returns to a single current version.
5. Start a clean rotation: run `aws secretsmanager rotate-secret` and watch the version labels progress from `AWSPENDING` to `AWSCURRENT`. Expected: rotation completes and the schedule resumes.

## When to use
- `describe-secret` shows an `AWSPENDING` version that never resolves
- Rotation worked before and now hangs
- You need to safely unwind a failed rotation before retrying

## When not to use
- Setting up rotation for the first time (follow the setup guide instead)
- `AccessDenied` on the Lambda itself (fix IAM first, then recover here)
- Application code reading the wrong version label (client-side issue)

## Tool compatibility
- AWS CLI v2, Secrets Manager rotation with Lambda; CloudWatch Logs for diagnosis

## Variant phrasings
### rotation lambda timed out leaving AWSPENDING
Increase the Lambda timeout and memory, fix the underlying slowness, then cancel and re-rotate; the stale pending version cannot be resumed.

### secretsmanager rotation never finishes
Check `RotationRules` for a sane schedule and confirm the Lambda has network access to the target database.

## Why it happens
Secrets Manager rotation is a four-step state machine driven by the Lambda (create, set, test, finish). If the Lambda throws at any step, the state machine halts with the new version labeled `AWSPENDING`. The API will not auto-retry a halted rotation, so manual cancel plus a fresh rotate is the recovery path.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_sxHZ9Frd2Wf16yNM0OioSQ