## TL;DR
Archived versions are read-only: a version in the Archived stage cannot transition stages until it is restored, and in newer MLflow versions stages are deprecated in favor of aliases. Check the version's current stage first; if it is archived, the fix is to register a new version or restore where the server allows it, and for promotion flows prefer setting an alias such as champion on the target version.

```text
MLflow model registry error: transition_model_version_stage failed for archived version
```

## Use this when
- The run or call fails with this symptom: transition_model_version_stage failed for an archived model version.
- You are working on an MLflow registry promotion flow moving a version to a production stage and the failure repeats on the same run or configuration.
- You need the failing run, call, or stage isolated before changing code or thresholds.

## Not for this skill when
- A version archived by mistake minutes ago, where restoring it is the intended path rather than registering anew.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Fetch the model version and record its current stage and status before attempting any transition. Verify: the version's stage is confirmed as Archived
2. Decide the intent: promote this exact artifact, which needs a new registered version from the same source, or un-archive where the deployment still uses stages and allows it. Verify: one recovery path is chosen explicitly
3. Carry out the chosen path and verify the registry shows the version reachable under the stage or alias the deploy uses. Verify: the deploy's stage or alias resolves to the intended version
4. Update the promotion script to check stage first and to set aliases instead of stages on current MLflow. Verify: the script no longer attempts transitions from Archived

## Variant phrasings
### mlflow transition model version stage archived error
The verbatim phrasing.
### mlflow archived version cannot promote stage
The promotion phrasing.
### mlflow model registry stage transition failed fix
The fix phrasing.

Compatibility: MLflow 2.x and 3.x model registry stage transitions

## Why it happens
Archiving is a terminal housekeeping state meant to remove a version from active use, so the registry blocks lifecycle moves out of it through the normal transition call. Promotion automation that never checks the current stage discovers this only when an old version is re-promoted.

## Edge cases / pitfalls
- Stage names are case-sensitive in the API; a wrong-case stage produces a different, confusing error.
- Aliases and stages can coexist; a deploy reading the alias will not notice a stage fix, so verify which one it reads.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0WVw9txonmTiiMS07p1-vg